lobehub/lobe-editor

GitHub: lobehub/lobe-editor

基于 Lexical 框架的双架构富文本编辑器，专为 AI 应用和聊天界面打造，提供丰富的插件生态和 React 集成。

Stars: 158 | Forks: 21

LobeHub Editor

一个现代、可扩展的富文本编辑器，基于 Meta 的 Lexical 框架构建，采用双架构设计，同时提供强大的内核和 React 集成。专为 AI 应用和聊天界面优化。 [![](https://img.shields.io/npm/v/@lobehub/editor?color=369eff&labelColor=black&logo=npm&logoColor=white&style=flat-square)][npm-release-link] [![](https://img.shields.io/github/release-date/lobehub/lobe-editor?labelColor=black&style=flat-square)][github-releasedate-link] [![](https://img.shields.io/github/actions/workflow/status/lobehub/lobe-editor/test.yml?label=test&labelColor=black&logo=githubactions&logoColor=white&style=flat-square)][github-action-test-link] [![](https://img.shields.io/github/actions/workflow/status/lobehub/lobe-editor/release.yml?label=release&labelColor=black&logo=githubactions&logoColor=white&style=flat-square)][github-action-release-link]
[![](https://img.shields.io/github/contributors/lobehub/lobe-editor?color=c4f042&labelColor=black&style=flat-square)][github-contributors-link] [![](https://img.shields.io/github/forks/lobehub/lobe-editor?color=8ae8ff&labelColor=black&style=flat-square)][github-forks-link] [![](https://img.shields.io/github/stars/lobehub/lobe-editor?color=ffcb47&labelColor=black&style=flat-square)][github-stars-link] [![](https://img.shields.io/github/issues/lobehub/lobe-editor?color=ff80eb&labelColor=black&style=flat-square)][github-issues-link] [![](https://img.shields.io/github/license/lobehub/lobe-editor?color=white&labelColor=black&style=flat-square)][github-license-link] [更新日志](./CHANGELOG.md) · [报告 Bug][github-issues-link] · [提出功能建议][github-issues-link] ![](https://static.pigsec.cn/wp-content/uploads/repos/cas/70/7094088a48b77c65bbbcdfb1fcdb263cba21d9b2417870ecd37d14a4b827c110.png)
目录 #### 目录 - [✨ 特性](#-features) - [📦 安装说明](#-installation) - [🚀 快速开始](#-quick-start) - [基础编辑器](#basic-editor) - [插件进阶用法](#advanced-usage-with-plugins) - [聊天输入组件](#chat-input-component) - [编辑器内核 API](#editor-kernel-api) - [🔌 可用插件](#-available-plugins) - [核心插件](#core-plugins) - [内容插件](#content-plugins) - [插件架构](#plugin-architecture) - [插件特性](#plugin-features) - [📖 API 参考](#-api-reference) - [编辑器内核](#editor-kernel) - [插件系统](#plugin-system) - [🛠️ 开发指南](#️-development) - [环境配置](#setup) - [可用脚本](#available-scripts) - [调试环境变量](#debug-environment-variables) - [项目架构](#project-architecture) - [🤝 贡献指南](#-contributing) - [🔗 相关链接](#-links) - [更多产品](#more-products) - [设计资源](#design-resources) - [开发资源](#development-resources) ####
## ✨ 特性 - 🎯 **双架构设计** - 同时提供基于内核的 API 和 React 组件，实现最大的灵活性 - ⚛️ **React 优先** - 为 React 19+ 打造，采用现代 hooks 和设计模式 - 🔌 **丰富的插件生态** - 10+ 内置插件，满足全面的内容编辑需求 - 💬 **专为聊天界面打造** - 预置支持 mention 的聊天输入组件 - ⌨️ **斜杠命令** - 直观的 `/` 和 `@` 触发菜单，快速插入内容 - 📝 **多种导出格式** - 支持 JSON、Markdown 和纯文本导出 - 🎨 **可定制的 UI** - 采用 Antd 风格组件，支持灵活的主题设置 - 🔗 **文件与媒体支持** - 原生支持图片、文件、表格等 - 🎯 **TypeScript 原生支持** - 使用 TypeScript 构建，提供卓越的开发者体验 - 📱 **现代构建系统** - 由 Vite、Dumi 文档和全面测试体系优化 ## 📦 安装说明 要安装 `@lobehub/editor`，请运行以下命令： [![](https://img.shields.io/badge/-speedup%20with%20bun-black?logo=bun&style=for-the-badge)][bun-link] ``` $ bun add @lobehub/editor ``` ``` $ pnpm add @lobehub/editor ```
\[!\[][back-to-top\]](#readme-top)
## 🚀 快速开始 ### 基础编辑器 使用全功能编辑器最简单的方式： ``` import { INSERT_HEADING_COMMAND, ReactCodeblockPlugin, ReactImagePlugin, ReactLinkPlugin, ReactListPlugin, } from '@lobehub/editor'; import { Editor, useEditor } from '@lobehub/editor/react'; export default function MyEditor() { const editor = useEditor(); return ( { editor.dispatchCommand(INSERT_HEADING_COMMAND, { tag: 'h1' }); }, }, // More slash commands... ], }} onChange={(editor) => { // Handle content changes const markdown = editor.getDocument('markdown'); const json = editor.getDocument('json'); }} /> ); } ``` ### 插件进阶用法 使用内置插件添加更多功能： ``` import { INSERT_FILE_COMMAND, INSERT_MENTION_COMMAND, INSERT_TABLE_COMMAND, ReactFilePlugin, ReactHRPlugin, ReactTablePlugin, } from '@lobehub/editor'; import { Editor, useEditor } from '@lobehub/editor/react'; export default function AdvancedEditor() { const editor = useEditor(); return ( { // Handle file upload return { url: await uploadFile(file) }; }, }), ]} mentionOption={{ items: async (search) => [ { key: 'user1', label: 'John Doe', onSelect: (editor) => { editor.dispatchCommand(INSERT_MENTION_COMMAND, { label: 'John Doe', extra: { userId: 1 }, }); }, }, ], }} /> ); } ``` ### 聊天输入组件 专为聊天界面优化的预置组件： ``` import { ChatInput } from '@lobehub/editor/react'; export default function ChatApp() { return ( { // Handle message send console.log('Message:', content); }} enabledFeatures={['mention', 'upload', 'codeblock']} /> ); } ``` ### 编辑器内核 API 对于进阶用例，可直接访问底层内核： ``` import { IEditor, createEditor } from '@lobehub/editor'; // Create editor instance const editor: IEditor = createEditor(); // Register plugins editor.registerPlugin(SomePlugin, { config: 'value' }); // Interact with content editor.setDocument('text', 'Hello world'); const content = editor.getDocument('json'); // Listen to events editor.on('content-changed', (newContent) => { console.log('Content updated:', newContent); }); // Execute commands editor.dispatchCommand(INSERT_HEADING_COMMAND, { tag: 'h2' }); ```
\[!\[][back-to-top\]](#readme-top)
## 🔌 可用插件 ### 核心插件 | Plugin | 描述 | 特性 | | ------------------ | ---------------------- | --------------------------------------------------------------- | | **CommonPlugin** | 基础编辑器组件 | ReactEditor, ReactEditorContent, ReactPlainText, 基础工具 | | **MarkdownPlugin** | Markdown 处理引擎 | 快捷方式、转换器、序列化、自定义 writer | | **UploadPlugin** | 文件上传管理系统 | 优先级处理器、拖拽上传、多源上传 | ### 内容插件 | Plugin | 描述 | 特性 | | ------------------------ | ------------------ | --------------------------------------------------------------- | | **ReactSlashPlugin** | 斜杠命令菜单系统 | `/` 和 `@` 触发菜单、自定义项、异步搜索 | | **ReactMentionPlugin** | 用户 mention 支持 | `@username` mentions、自定义 Markdown 输出、异步用户搜索 | | **ReactImagePlugin** | 图片处理 | 上传、显示、拖拽、说明文字、调整大小 | | **ReactCodeblockPlugin** | 代码语法高亮 | 基于 Shiki、支持 100+ 语言、自定义主题、配色方案 | | **ReactListPlugin** | 列表管理 | 有序/无序列表、嵌套列表、键盘快捷键 | | **ReactLinkPlugin** | 链接管理 | 自动检测、验证、预览、自定义样式 | | **ReactTablePlugin** | 表格支持 | 插入表格、编辑单元格、添加/删除行/列、i18n | | **ReactHRPlugin** | 分割线 | 插入分割线、自定义样式、Markdown 快捷方式 | | **ReactFilePlugin** | 文件附件 | 文件上传、状态追踪、验证、拖拽 | ### 插件架构 所有插件均遵循**双架构设计**： #### 🧠 **内核层**（框架无关） - **Plugin Interface**：带有生命周期管理的标准化插件系统 - **Service Container**：集中式的服务注册和依赖注入 - **Command System**：用于编辑器操作的事件驱动命令模式 - **Node System**：具有序列化和转换功能的自定义节点类型 - **Data Sources**：内容管理和格式转换（JSON、Markdown、Text） #### ⚛️ **React 层**（React 专属） - **React Components**：用于轻松集成的高级组件 - **Hook Integration**：用于编辑器状态和功能的自定义 hooks - **Event Handling**：对 React 友好的事件系统和回调 - **UI Components**：支持主题的预置 UI 元素 ### 插件特性 - ✅ **完全可配置**，提供 TypeScript 类型选项 - ✅ **可组合使用** - 任意搭配组合 - ✅ **可扩展** - 使用相同的 API 创建自定义插件 - ✅ **事件驱动** - 响应用户交互和内容更改 - ✅ **面向服务** - 带有依赖注入的模块化架构 - ✅ **国际化** - 在适用的地方内置 i18n 支持 - ✅ **Markdown 集成** - 快捷方式、导入/导出、自定义转换器 - ✅ **主题系统** - 可定制的样式和外观 - ✅ **命令模式** - 程序化控制和自动化 ## 📖 API 参考 #### 实用 Hooks ``` // Get editor instance const editor = useEditor(); // Helper for plugin configuration const PluginWithConfig = Editor.withProps(ReactFilePlugin, { handleUpload: async (file) => ({ url: 'uploaded-url' }), }); ``` ### 编辑器内核 #### `createEditor(): IEditor` 创建一个新的编辑器内核实例： ``` const editor = createEditor(); ``` #### `IEditor` 接口 核心编辑器方法： ``` interface IEditor { // Content management setDocument(type: string, content: any): void; getDocument(type: string): any; // Plugin system registerPlugin(plugin: Constructor, config?: T): IEditor; registerPlugins(plugins: Plugin[]): IEditor; // Commands dispatchCommand(command: LexicalCommand, payload: T): boolean; // Events on(event: string, listener: (data: T) => void): this; off(event: string, listener: (data: T) => void): this; // Lifecycle focus(): void; blur(): void; destroy(): void; // Access getLexicalEditor(): LexicalEditor | null; getRootElement(): HTMLElement | null; requireService(serviceId: ServiceID): T | null; } ``` ### 插件系统 #### 创建自定义插件 ``` import { IEditorKernel, IEditorPlugin } from '@lobehub/editor'; class MyCustomPlugin implements IEditorPlugin { constructor(private config: MyPluginConfig) {} initialize(kernel: IEditorKernel) { // Register nodes, commands, transforms, etc. kernel.registerNode(MyCustomNode); kernel.registerCommand(MY_COMMAND, this.handleCommand); } destroy() { // Cleanup } } ``` #### 可用命令 你可以分发的常用命令： ``` // Content insertion INSERT_HEADING_COMMAND; // { tag: 'h1' | 'h2' | 'h3' } INSERT_LINK_COMMAND; // { url: string, text?: string } INSERT_IMAGE_COMMAND; // { src: string, alt?: string } INSERT_TABLE_COMMAND; // { rows: number, columns: number } INSERT_MENTION_COMMAND; // { label: string, extra?: any } INSERT_FILE_COMMAND; // { file: File } INSERT_HORIZONTAL_RULE_COMMAND; // Text formatting FORMAT_TEXT_COMMAND; // { format: 'bold' | 'italic' | 'underline' } CLEAR_FORMAT_COMMAND; ```
\[!\[][back-to-top\]](#readme-top)
## 🛠️ 开发指南 ### 环境配置 你可以使用 Github Codespaces 进行在线开发： [![](https://static.pigsec.cn/wp-content/uploads/repos/cas/42/420ddeb50c67e8a211b122a8a95dc6641446c7cd01f2984d6ef2c368c1c55c86.svg)][github-codespace-link] 或者克隆到本地进行开发： [![](https://img.shields.io/badge/-speedup%20with%20bun-black?logo=bun&style=for-the-badge)][bun-link] ``` $ git clone https://github.com/lobehub/lobe-editor.git $ cd lobe-editor $ pnpm install $ pnpm run dev ``` 这将在 `http://localhost:8000` 启动带有实时演练场的 Dumi 文档服务器。 ### 可用脚本 | Script | 描述 | | -------------------- | -------------------------------------------- | | `pnpm dev` | 启动带有演练场的 Dumi 开发服务器 | | `pnpm build` | 构建库并生成类型定义 | | `pnpm test` | 使用 Vitest 运行测试 | | `pnpm test:coverage` | 运行测试并生成覆盖率报告 | | `pnpm lint` | 使用 ESLint 进行代码检查和修复 | | `pnpm type-check` | 使用 TypeScript 进行类型检查 | | `pnpm ci` | 运行所有 CI 检查（lint、type-check、test） | | `pnpm docs:build` | 构建生产环境的文档 | | `pnpm release` | 使用 semantic-release 发布新版本 | ### 调试环境变量 LobeHub Editor 包含全面的调试日志记录功能，可通过环境变量进行控制： #### 基础调试配置 ``` # 启用所有 LobeHub Editor 调试输出 DEBUG=lobe-editor:* # 仅启用重要日志（推荐用于开发） DEBUG=lobe-editor:*:info,lobe-editor:*:warn,lobe-editor:*:error # 启用特定组件 DEBUG=lobe-editor:kernel,lobe-editor:plugin:* ``` #### 可用调试类别 | Category | 描述 | 示例 | | ------------------- | ------------------ | ----------------------------------- | | `kernel` | 核心编辑器功能 | `DEBUG=lobe-editor:kernel` | | `plugin:*` | 所有插件 | `DEBUG=lobe-editor:plugin:*` | | `plugin:slash` | 斜杠命令 | `DEBUG=lobe-editor:plugin:slash` | | `plugin:mention` | Mention 系统 | `DEBUG=lobe-editor:plugin:mention` | | `plugin:image` | 图片处理 | `DEBUG=lobe-editor:plugin:image` | | `plugin:file` | 文件操作 | `DEBUG=lobe-editor:plugin:file` | | `service:*` | 所有服务 | `DEBUG=lobe-editor:service:*` | | `service:upload` | 上传服务 | `DEBUG=lobe-editor:service:upload` | | `service:markdown` | Markdown 处理 | `DEBUG=lobe-editor:service:markdown`| #### 调试级别 | 级别 | 浏览器显示 | 用途 | 环境变量 | | ------- | -------------------- | -------------- | --------------------------- | | `debug` | Console.log (灰色) | 详细追踪 | `DEBUG=lobe-editor:*:debug` | | `info` | Console.log (蓝色) | 常规信息 | `DEBUG=lobe-editor:*:info` | | `warn` | Console.warn (黄色) | 警告信息 | `DEBUG=lobe-editor:*:warn` | | `error` | Console.error (红色) | 错误信息 | `DEBUG=lobe-editor:*:error` | #### 开发环境用法 ``` # 开发期间全面调试 DEBUG=lobe-editor:* # 仅关键日志 DEBUG=lobe-editor:*:error,lobe-editor:*:warn # Plugin 调试 DEBUG=lobe-editor:plugin:* # Service 调试 DEBUG=lobe-editor:service:* ``` ### 项目架构 ``` lobe-editor/ ├── src/ │ ├── editor-kernel/ # 🧠 Core editor logic │ │ ├── kernel.ts # Main editor class with plugin system │ │ ├── data-source.ts # Content management (JSON/Markdown/Text) │ │ ├── service.ts # Service container and dependency injection │ │ ├── plugin/ # Plugin base classes and interfaces │ │ ├── react/ # React integration layer │ │ └── types.ts # TypeScript interfaces │ │ │ ├── plugins/ # 🔌 Feature plugins │ │ ├── common/ # 🏗️ Foundation components │ │ │ ├── plugin/ # Base editor plugin │ │ │ ├── react/ # ReactEditor, ReactEditorContent, ReactPlainText │ │ │ ├── data-source/ # Content data sources │ │ │ └── utils/ # Common utilities │ │ │ │ │ ├── markdown/ # 📝 Markdown processing engine │ │ │ ├── plugin/ # Markdown transformation plugin │ │ │ ├── service/ # Markdown shortcut service │ │ │ ├── data-source/ # Markdown serialization │ │ │ └── utils/ # Transformer utilities │ │ │ │ │ ├── upload/ # 📤 Upload management system │ │ │ ├── plugin/ # Upload handling plugin │ │ │ ├── service/ # Upload service with priority system │ │ │ └── utils/ # Upload utilities │ │ │ │ │ ├── slash/ # ⚡ Slash commands (/, @) │ │ │ ├── plugin/ # Slash detection plugin │ │ │ ├── react/ # ReactSlashPlugin, ReactSlashOption │ │ │ ├── service/ # Slash service with fuzzy search │ │ │ └── utils/ # Search and trigger utilities │ │ │ │ │ ├── mention/ # 👤 @mention system │ │ │ ├── plugin/ # Mention plugin with decorators │ │ │ ├── react/ # ReactMentionPlugin │ │ │ ├── command/ # INSERT_MENTION_COMMAND │ │ │ └── node/ # MentionNode with serialization │ │ │ │ │ ├── codeblock/ # 🎨 Syntax highlighting │ │ │ ├── plugin/ # Codeblock plugin with Shiki │ │ │ ├── react/ # ReactCodeblockPlugin │ │ │ ├── command/ # Language and color commands │ │ │ └── utils/ # Language detection │ │ │ │ │ ├── image/ # 🖼️ Image upload & display │ │ │ ├── plugin/ # Image plugin with captions │ │ │ ├── react/ # ReactImagePlugin │ │ │ ├── command/ # INSERT_IMAGE_COMMAND │ │ │ └── node/ # BaseImageNode, ImageNode │ │ │ │ │ ├── table/ # 📊 Table support │ │ │ ├── plugin/ # Table plugin with i18n │ │ │ ├── react/ # ReactTablePlugin │ │ │ ├── command/ # Table manipulation commands │ │ │ ├── node/ # Enhanced TableNode │ │ │ └── utils/ # Table operations │ │ │ │ │ ├── file/ # 📎 File attachments │ │ │ ├── plugin/ # File plugin with status tracking │ │ │ ├── react/ # ReactFilePlugin │ │ │ ├── command/ # INSERT_FILE_COMMAND │ │ │ ├── node/ # FileNode with metadata │ │ │ └── utils/ # File operations │ │ │ │ │ ├── link/ # 🔗 Link management │ │ │ ├── plugin/ # Link plugin with validation │ │ │ ├── react/ # ReactLinkPlugin │ │ │ ├── command/ # Link commands │ │ │ └── utils/ # URL validation and detection │ │ │ │ │ ├── list/ # 📋 Lists (ordered/unordered) │ │ │ ├── plugin/ # List plugin with nesting │ │ │ ├── react/ # ReactListPlugin │ │ │ ├── command/ # List manipulation commands │ │ │ └── utils/ # List operations │ │ │ │ │ └── hr/ # ➖ Horizontal rules │ │ ├── plugin/ # HR plugin with styling │ │ ├── react/ # ReactHRPlugin │ │ ├── command/ # HR insertion commands │ │ └── node/ # HorizontalRuleNode │ │ │ ├── react/ # ⚛️ High-level React components │ │ ├── Editor/ # Main Editor component with plugins │ │ ├── ChatInput/ # Chat interface component │ │ ├── ChatInputActions/ # Chat action buttons │ │ ├── ChatInputActionBar/ # Action bar layout │ │ ├── SendButton/ # Send button with states │ │ └── CodeLanguageSelect/ # Code language selector │ │ │ └── index.ts # Public API exports │ ├── docs/ # 📚 Documentation source ├── tests/ # 🧪 Test files ├── vitest.config.ts # Test configuration └── .dumi/ # Dumi doc build cache ``` 该架构遵循**双层设计**： 1. **内核层** (`editor-kernel/`) - 框架无关的核心及插件系统 2. **React 层** (`react/` + `plugins/*/react/`) - React 专属实现 每个插件都遵循一致的结构： - **`plugin/`** - 核心插件逻辑和节点定义 - **`react/`** - React 组件和 hooks（如果适用） - **`command/`** - 编辑器命令和处理器 - **`service/`** - 服务和业务逻辑 - **`node/`** - 自定义 Lexical 节点 - **`utils/`** - 实用功能和辅助工具 这提供了最大的灵活性——你可以仅使用内核进行自定义集成，或使用 React 组件进行快速开发。
[![](https://img.shields.io/badge/-BACK_TO_TOP-black?style=flat-square)](#readme-top)
## 🤝 贡献指南 我们非常欢迎任何类型的贡献。如果你有兴趣贡献代码，请随时查看我们的 GitHub [Issues][github-issues-link]，立即参与其中并大展身手吧。 [![](https://img.shields.io/badge/%F0%9F%A4%AF%20PR%20WELCOME-%E2%86%92-ffcb47?labelColor=black&style=for-the-badge)][pr-welcome-link] [![](https://contrib.rocks/image?repo=lobehub%2Flobe-editor)][github-contrib-link]
[![](https://img.shields.io/badge/-BACK_TO_TOP-black?style=flat-square)](#readme-top)
## 🔗 相关链接 ### 更多产品 - **[🤯 Lobe Chat](https://github.com/lobehub/lobe-chat)** - 一个开源、可扩展Function Calling）、高性能的聊天机器人框架。支持一键免费部署你私有的 ChatGPT/LLM Web 应用。 - **[🅰️ Lobe Theme](https://github.com/lobehub/sd-webui-lobe-theme)** - Stable diffusion webui 的现代主题，精致的界面设计、高度可定制的 UI 以及提升效率的功能。 - **[🧸 Lobe Vidol](https://github.com/lobehub/lobe-vidol)** - 使用 Lobe Vidol 体验虚拟偶像创作的魔力，享受我们精美 UI 设计的优雅，利用 MMD 舞蹈支持随之起舞，并体验流畅的对话。 ### 设计资源 - **[🍭 Lobe UI](https://ui.lobehub.com)** - 用于构建 AIGC Web 应用的开源 UI 组件库。 - **[🥨 Lobe Icons](https://lobehub.com/icons)** - 热门 AI / LLM 模型品牌 SVG Logo 和图标合集。 - **[📊 Lobe Charts](https://charts.lobehub.com)** - 基于 recharts 构建的 React 现代图表组件 ### 开发资源 - **[🎤 Lobe TTS](https://tts.lobehub.com)** - 适用于服务端和浏览器的高质量、可靠的 TTS/STT 库 - **[🌏 Lobe i18n](https://github.com/lobehub/lobe-cli-toolbox/blob/master/packages/lobe-i18n)** - 用于 i18n（国际化）翻译过程的自动化 AI 工具。 [更多资源](https://lobehub.com/resources)
[![](https://img.shields.io/badge/-BACK_TO_TOP-black?style=flat-square)](#readme-top)
#### 📝 License Copyright © 2025 [LobeHub][profile-link].
本项目基于 [MIT](./LICENSE) 协议授权。
标签：AI应用, Lexical框架, React组件, 富文本编辑器, 自定义脚本