富文本编辑器的内容契约:Tiptap、Monaco 与 CodeMirror
本文目录
编辑器不是在 textarea 外面套一圈按钮。一个内容平台至少有输入、持久化、预览、公开渲染四条链路:在后台能看到的内容,发布后也必须能稳定解释。先确定内容模型,再选择编辑器,能少掉很多“编辑时正常,发布后乱码或丢格式”的问题。
三类编辑器不能混为一谈
| 类别 | 候选 | 适用场景 | 主要契约 |
|---|---|---|---|
| 结构化富文本 | Tiptap、TinyMCE、CKEditor、wangEditor | 图文文章、批注、结构化模块 | 节点 schema、扩展版本、粘贴规则 |
| 代码编辑器 | Monaco、CodeMirror | JSON、代码、配置文件 | 文本、语言服务、诊断与资源清理 |
| Markdown 输入与预览 | TOAST UI Editor、SimpleMDE 等 | 技术文章、可移植纯文本 | Markdown 方言、扩展语法、安全渲染 |
Monaco 的语言服务、worker、主题和快捷键适合代码操作台,但它不会替你解决文章排版。CodeMirror 的扩展组合也需要明确版本。Tiptap 基于结构化文档和扩展工作,不提供现成的全套产品界面。工具栏、上传交互、无障碍、自动保存仍要自己设计。
一份内容必须有确定的权威格式
如果选 Tiptap JSON 为权威数据,保存 JSON 和 schema 版本;HTML 可以是派生产物。若 Markdown 是权威数据,富文本模式必须明确哪些语法能无损往返。表格、数学公式、自定义音视频块、批注锚点,都是常见的往返损失点。
type StoredDocument = {
schemaVersion: number;
revision: number;
format: 'tiptap-json';
content: Record<string, unknown>;
};
schemaVersion 是解释文档的规则版本,revision 是某一篇文章的修改版本,两者不能互换。删除扩展前先扫描历史节点,做迁移或保留兼容渲染;不要让旧内容遇到未知节点时静默消失。
React 接入示意
下面面向 Tiptap 的 React 接入方式;安装相互兼容的核心、React 和 StarterKit 版本。服务端渲染场景要避免在服务端创建依赖浏览器的编辑器。
import { useEditor, EditorContent } from '@tiptap/react';
import StarterKit from '@tiptap/starter-kit';
export function ArticleEditor({ initialJSON, onChange }) {
const editor = useEditor({
extensions: [StarterKit],
content: initialJSON,
immediatelyRender: false,
onUpdate: ({ editor }) => onChange(editor.getJSON()),
});
return <section aria-label="文章正文编辑器">
<EditorContent editor={editor} />
</section>;
}
这是输入端示意,不是完整的发布系统。切换文章时,不能把上一篇尚未完成的请求结果写入下一篇;应按文章 ID 建立编辑实例边界,或显式重置内容和撤销历史。服务端仍需验证节点类型、长度、URL 协议和附件归属。
保存需要防止覆盖新内容
保存开始时捕获一个快照,提交时带上已知 revision,服务端原子检查。以下是协议示意,实际接口路径按项目定义:
async function saveDraft(id, revision, content, signal) {
const response = await fetch('/api/documents/' + encodeURIComponent(id), {
method: 'PUT',
headers: {
'Content-Type': 'application/json',
'If-Match': '"' + revision + '"',
},
body: JSON.stringify({ format: 'tiptap-json', schemaVersion: 1, content }),
signal,
});
if (response.status === 412) throw new Error('内容已被更新,请先比较版本');
if (!response.ok) throw new Error('保存失败,草稿仍保留在本地');
return response.json();
}
AbortController 可以停止前端等待,却不能保证服务器尚未写入。重试要有幂等设计,覆盖要有版本比较。响应返回后,如果用户已经继续输入,就只能更新“已保存快照”,不能把当前 dirty 状态无条件清零。自动保存还应串行或防止旧响应覆盖新版本。
预览安全与附件
解析 Markdown 和净化 HTML 是两个步骤;代码高亮不是 Markdown 解析器。HTML 渲染前限制危险标签和属性,链接只允许期望的协议,服务端同样校验。插入图片应先上传再记录附件 ID,而不是依赖临时 blob URL;失败后允许重试,不删除用户输入。
粘贴大图、超长代码、复杂表格时,限制节点和附件大小,并显示明确错误。不要为了修复粘贴效果开放任意 script、iframe 或 style。需要在线案例时,用有权限约束的独立沙箱模块。
移动端与验收
工具栏允许横向滚动或折叠,正文容器允许收缩,弹层必须在软键盘出现后仍能操作。固定工具栏不要遮住选区或页面导航;快捷键与浏览器冲突时提供可见按钮。
至少验证:粘贴、撤销重做、切换文章、断网保存、跨标签编辑冲突、公式和媒体往返、历史版本回退、未保存离开、键盘选区和手机旋转。空文档、未知节点、历史格式都需要明确表现,不能直接白屏。
官方资料
资源发现来源:腾讯云前端资源清单、25 项前端资源清单。本文按内容平台的实际工程问题重新组织。
留言提交后直接公开,请友善交流。