ModaEditor — 富文本编辑器

无头编辑器核心 — React/Vue/Svelte/vanilla。

基于不可变 JSON AST 文档和事务更新的框架无关无头富文本编辑器。

文档模型、事务、选区、输入绑定等全部编辑器逻辑放在纯 TypeScript 核心,各框架适配器只做轻量响应式绑定。5 个渲染器生成相同 DOM 契约,各处行为一致。

一个入门包即涵盖格式、标题、引用、列表、任务、表格、代码块、链接、图片、对齐、历史——Extension/Plugin/InputRule 可无限扩展。

免费 (MIT)React · Vue 3 · Vue 2.7 · Svelte 5 · Vanilla不可变 EditorState · 事务TypeScript

实时演示

使用从 CDN 加载的真实核心运行。工具栏每个按钮与 editor.commands.* 调用一一对应(悬停显示 API 名),每次编辑都会在下面板实时输出 HTML 序列化和文档 JSON,底部可看到 editor.on() 订阅的事件流。

各环境包

使用环境包备注
React@moda-editor/reactuseEditor + EditorView,自定义节点视图为React组件
Vue 3@moda-editor/vueuseEditor + EditorView SFC,useEditorState外部订阅编辑器
Vue 2.7@moda-editor/vue2与Vue 3相同的Composition API用法
Svelte 5@moda-editor/sveltecreateEditorStore + EditorView,readable store联动
纯JS / CDNmoda-editor.js无需构建工具,一行<script>,window.ModaEditor
无框架@moda-editor/core直接使用无头createEditor + mountEditor

npm 安装

npm i @moda-editor/react # React
npm i @moda-editor/vue # Vue 3
npm i @moda-editor/vue2 # Vue 2.7
npm i @moda-editor/svelte # Svelte 5
npm i @moda-editor/core # 仅无头核心
npmjs.com/package/@moda-editor/react →

CDN 直接使用

https://editor.modaolive.com/moda-editor.js
https://editor.modaolive.com/style.css

三步开始

  1. 1

    安装包

    安装适配器如 npm i @moda-editor/react,或用一行 CDN <script> 加载核心。

  2. 2

    传extensions

    一个 starterExtensions() 就包含模式·命令·键映射·输入规则·历史。可用 doc 传入初始文档 JSON。

  3. 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·Ucommands.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-EntersplitBlock / exitBlock 命令

列表·表格

功能启用方式 (选项/prop/输入)核心API
无序·有序列表工具栏按钮commands.toggleBulletList() / toggleOrderedList()
待办列表工具栏按钮commands.toggleTaskList() / toggleTaskItem()
缩进·减少缩进Tab / Shift-Tabcommands.sinkListItem() / liftListItem()
插入表格·行·列—commands.insertTable(r,c) / addTableRow / addTableColumn / deleteTable
单元格移动表格内 TabnextCell / 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-Zcommands.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。

rich text editor

相关工具