ModaEditor — 富文本编辑器
无头编辑器核心 — React/Vue/Svelte/vanilla。
基于不可变 JSON AST 文档和事务更新的框架无关无头富文本编辑器。
文档模型、事务、选区、输入绑定等全部编辑器逻辑放在纯 TypeScript 核心,各框架适配器只做轻量响应式绑定。5 个渲染器生成相同 DOM 契约,各处行为一致。
一个入门包即涵盖格式、标题、引用、列表、任务、表格、代码块、链接、图片、对齐、历史——Extension/Plugin/InputRule 可无限扩展。
实时演示
使用从 CDN 加载的真实核心运行。工具栏每个按钮与 editor.commands.* 调用一一对应(悬停显示 API 名),每次编辑都会在下面板实时输出 HTML 序列化和文档 JSON,底部可看到 editor.on() 订阅的事件流。
各环境包
| 使用环境 | 包 | 备注 |
|---|---|---|
| React | @moda-editor/react | useEditor + EditorView,自定义节点视图为React组件 |
| Vue 3 | @moda-editor/vue | useEditor + EditorView SFC,useEditorState外部订阅编辑器 |
| Vue 2.7 | @moda-editor/vue2 | 与Vue 3相同的Composition API用法 |
| Svelte 5 | @moda-editor/svelte | createEditorStore + EditorView,readable store联动 |
| 纯JS / CDN | moda-editor.js | 无需构建工具,一行<script>,window.ModaEditor |
| 无框架 | @moda-editor/core | 直接使用无头createEditor + mountEditor |
npm 安装
npm i @moda-editor/react # Reactnpm i @moda-editor/vue # Vue 3npm i @moda-editor/vue2 # Vue 2.7npm i @moda-editor/svelte # Svelte 5npm i @moda-editor/core # 仅无头核心CDN 直接使用
https://editor.modaolive.com/moda-editor.jshttps://editor.modaolive.com/style.css三步开始
- 1
安装包
安装适配器如 npm i @moda-editor/react,或用一行 CDN <script> 加载核心。
- 2
传extensions
一个 starterExtensions() 就包含模式·命令·键映射·输入规则·历史。可用 doc 传入初始文档 JSON。
- 3
渲染·操作
适配器只需一个 <EditorView>。工具栏连接 editor.commands.*,vanilla 用 mountEditor(el, options) 接线。
// npm i @moda-editor/react
import { EditorView, starterExtensions, useEditor } from "@moda-editor/react";
import "@moda-editor/react/styles.css";
function App() {
const { editor, state } = useEditor({
doc: myDoc, // DocNode JSON(省略则为空文档)
extensions: starterExtensions(), // 入门模式·命令·键映射·历史
});
return (
<>
<button onClick={() => editor.commands.toggleBold()}>B</button>
<button onClick={() => editor.commands.setHeading(2)}>H2</button>
<EditorView editor={editor} />
</>
);
}
// state 为不可变 EditorState — 用 === 比较决定是否重渲染EditorState 不可变——变更前返回同一引用,因此结构性保证 React useSyncExternalStore 的快照契约。
按功能使用 — 该用什么
所有功能由核心命令·选项驱动,适配器只做转发。悬停演示工具栏按钮即可看到对应 API。
格式 (行内标记)
| 功能 | 启用方式 (选项/prop/输入) | 核心API |
|---|---|---|
| 粗体·斜体·下划线 | 工具栏 / Mod-B·I·U | commands.toggleBold() / toggleItalic() / toggleUnderline() |
| 删除线 | 工具栏按钮 | commands.toggleStrike() |
| 上标·下标 | — | commands.toggleSuperscript() / toggleSubscript() |
| 行内代码 | 工具栏按钮 | commands.toggleCode() |
| 修改标记属性 | — | commands.setMarkAttr("link", { href }) |
| 清除格式 | — | clearFormat(starter 辅助函数) |
块
| 功能 | 启用方式 (选项/prop/输入) | 核心API |
|---|---|---|
| 标题 | 工具栏按钮 | commands.setHeading(1~6) |
| 引用 | 工具栏按钮 | commands.toggleQuote() |
| 代码块 | toggleCodeBlock — 含语言选择 | commands.setCodeLanguage(lang) / highlightCode |
| 水平线·硬换行 | — | commands.insertHorizontalRule() / insertHardBreak() |
| 对齐 | 注册对齐 feature 后 | commands.setAlign("left"|"center"|"right") |
| 块拆分·跳出 | Enter / Mod-Enter | splitBlock / exitBlock 命令 |
列表·表格
| 功能 | 启用方式 (选项/prop/输入) | 核心API |
|---|---|---|
| 无序·有序列表 | 工具栏按钮 | commands.toggleBulletList() / toggleOrderedList() |
| 待办列表 | 工具栏按钮 | commands.toggleTaskList() / toggleTaskItem() |
| 缩进·减少缩进 | Tab / Shift-Tab | commands.sinkListItem() / liftListItem() |
| 插入表格·行·列 | — | commands.insertTable(r,c) / addTableRow / addTableColumn / deleteTable |
| 单元格移动 | 表格内 Tab | nextCell / prevCell |
链接·图片·粘贴
| 功能 | 启用方式 (选项/prop/输入) | 核心API |
|---|---|---|
| 链接 | 工具栏 / [文本](url) 输入规则 | commands.setLink(href) / unsetLink() |
| 图片 | 插入 URL / 粘贴·拖放 | commands.insertImage(src, alt) / updateImage / deleteImage |
| 图片上传钩子 | onImageUpload 选项 — File → URL 异步转换 | 省略时立即以 FileReader data URL 插入 |
| HTML 粘贴净化 | 自动 — 移除 script·on*·javascript: | parseHTML + sanitizeHTML 内置管线 |
| Word·Google Docs 粘贴 | 自动 — 防止外部粗体污染与包裹层扁平化 | 外部文档粘贴时结构净化 + 跳过历史 |
| paste 事件 | — | editor.on("paste", ({html, text}) => …) |
状态·事件·历史
| 功能 | 启用方式 (选项/prop/输入) | 核心API |
|---|---|---|
| 不可变状态 | — | editor.state — 变更前同一引用 |
| 渲染订阅 | 适配器自动连接 | editor.subscribe(fn) / getSnapshot() |
| 语义事件 | — | editor.on("update"|"selectionUpdate"|"transaction"|"focus"|"blur"|"destroy") |
| 撤销·重做 | starterExtensions含history、Mod-Z / Mod-Shift-Z | commands.undo() / redo(), canUndo / canRedo |
| 只读 | EditorOptions.editable: false | 视图关闭contenteditable的信号 |
| 协作 (CRDT) | bindCollab — @moda-editor/collab-yjs | 经 subscribe·apply 的生命周期绑定,基于 Point 的位置映射 |
| 手动分发 | — | editor.dispatch(tr) — 所有更改的单一入口 |
文档·扩展
| 功能 | 启用方式 (选项/prop/输入) | 核心API |
|---|---|---|
| JSON文档模型 | doc: DocNode选项 | createDoc(content) / createText(text, marks) |
| HTML序列化 | — | serializeToHTML(doc, schema) |
| HTML → 文档 | — | parseHTML(html, schema) → createDoc(nodes) |
| 自定义节点视图 | EditorView的nodeViews prop | { codeBlock: MyComponent } — NodeViewProps |
| 扩展系统 | extensions数组 | Extension = nodes + marks + commands + keymap + inputRules + plugins |
| 入门包 | extensions: starterExtensions() | 模式·命令·键映射·输入规则·历史打包 |
| 主题 | styles.css的--me-* CSS变量 | .me-* DOM类约定自定义 |
常用配方
可直接复制的代码片段。
工具栏按钮连接
editor.commands是扩展收集的命令注册表 — 直接绑到按钮onClick
<button onClick={() => editor.commands.toggleBold()}>B</button>
<button onClick={() => editor.commands.setHeading(2)}>H2</button>
<button onClick={() => editor.commands.toggleTaskList()}>{t.todoL}</button>
<button onClick={() => editor.commands.undo()}>↶</button>
// 返回 false = 当前选区不可应用 → 用作按钮禁用信号自动保存 (update事件)
文档·选择变化时触发 — 防抖后发送到服务器
editor.on("update", ({ state, prevState }) => {
if (state.doc === prevState.doc) return; // 仅选区变化时跳过
scheduleSave(serializeToHTML(state.doc, editor.schema));
});
// 或直接保存文档 JSON
const payload = JSON.stringify(state.doc);HTML → 文档加载
解析现有HTML为初始文档 — 内置sanitizer去除危险标签
import { createEditor, createDoc, parseHTML, starterExtensions }
from "@moda-editor/core";
const extensions = starterExtensions();
const boot = createEditor({ extensions });
const doc = createDoc(parseHTML(savedHtml, boot.schema));
const editor = createEditor({ extensions, doc });图片上传
粘贴·拖放·选择的File替换为服务器上传URL
useEditor({
extensions: starterExtensions(),
onImageUpload: async (file) => {
const form = new FormData();
form.append("file", file);
const res = await fetch("/api/upload", { method: "POST", body: form });
return (await res.json()).url; // 编辑器将其作为 src 插入
},
});自定义节点视图 (React)
用自组件替换特定节点类型的渲染 — content渲染编辑出口
function CodeBlockView({ node, editor, path, content }: NodeViewProps) {
return (
<div className="my-codeblock">
<select onChange={(e) =>
editor.commands.setCodeLanguageAt(path, e.target.value)} />
{content} {/* 编辑区 — 必须渲染 */}
</div>
);
}
<EditorView editor={editor} nodeViews={{ codeBlock: CodeBlockView }} />事件日志·外部联动
transaction在过滤前发布所有tr — 调试·同步的最底层钩子
editor.on("transaction", ({ tr, state }) => console.log(tr.steps));
editor.on("paste", ({ html, text }) => console.log(t.pasteL, text));
editor.on("blur", () => saveDraft());
editor.on("destroy", () => cleanup());
// 与视图共享外部创建的编辑器
const editor = createEditor({ extensions: starterExtensions() });
<EditorView editor={editor} /> // 订阅由视图处理跨框架行为一致
React·Vue·Svelte·Vanilla 渲染器都生成相同的 DOM 契约(.me-* 类),并通过共享一致性规范(runWidgetConformance)验证。在一个平台学会的 API 和 CSS 变量(--me-*)在其他平台同样适用。
源码·文档
github.com/park-taejoon/moda-editor-releases- 平台指南 — React / Vue 3 / Vue 2.7 / Svelte 5 / Vanilla
- 功能指南 — 自定义nodeViews·可搜索列表示例
- 主题 — --me-* CSS变量·迁移映射文档
使用方法
无头编辑器核心 — React/Vue/Svelte/vanilla。