CKEditor5 是从零用TS重写 的现代富文本编辑器框架,不是简单的WYSIWYG,而是一套基于自定义数据模型 + MVC + 虚拟DOM的可扩展编辑引擎,插件化架构,原生支持实时协同;和 CKEditor4 完全不兼容,底层逻辑差异巨大。
一句话重点:CKEditor5 内部有一套独立数据模型,不是直接操作DOM,模型 ↔ 视图 ↔ 输出HTML是三层映射,这是它协同、可控、可校验的根基。
一、核心架构(最重要)
三层分离:Data Model(数据模型) → View(视图) → DOM
- Model(数据层,核心) 不是HTML,是结构化文档树(Node、Text、Attribute),只读、不可直接改DOM;所有操作(加粗、插入图片)都通过 transformation(转换) + operation(操作) 修改模型;撤销、协同、版本记录全部基于这一层。
- Schema:模型规则,定义什么标签、属性、嵌套关系合法(比如p里面不能放table),用来过滤非法内容、约束输入。
- Operation:原子操作(插入文本、设置属性、删除节点),协同就是同步operation。
2.View(视图层) 模型到可编辑DOM的中间层,CKEditor自研虚拟视图,监听选区、按键、粘贴;模型变更 → 视图自动刷新,单向数据流。
3.DOM(浏览器真实DOM) 只是渲染载体,不做数据源;禁止直接操作编辑器内部DOM,会和模型不同步。
配套核心概念:
- Command(命令) :所有功能统一封装成命令(
bold、insertImage),UI按钮只是调用命令,命令可以被拦截、禁用、覆写;推荐所有业务逻辑走Command,不要直接操作DOM - Plugin(插件) :一切都是插件,加粗、段落、撤销、图片全部是插件,没有内置"核心硬编码",按需引入、按需移除
- Conversion(转换) :两套转换
-
- Upcast:粘贴HTML/加载HTML → 转成Model(入库)
- Downcast:Model → 输出HTML(保存到后端)
- Selection(选区) :独立选区模型,跨协同、跨插件统一管理光标
- Batch:批量操作,一次batch里的所有修改,作为一条撤销记录
对比 CKEditor4:CK4 直接操作DOM,数据不可控;CK5 模型优先,先校验再渲染,天然适合协同、内容规范、脏数据过滤。
二、编辑器类型(Preset 预设)
官方提供4种开箱即用编辑器,选一个基础模板:
- ClassicEditor 经典编辑器(最常用):顶部固定工具栏,下方编辑区,传统表单富文本
- InlineEditor 行内编辑器:点击文字直接编辑,无固定工具栏,类似Medium
- BalloonEditor 气泡编辑器:选中文字弹出悬浮工具栏(气泡)
- BalloonBlockEditor 块级气泡编辑器:块左侧悬浮工具栏,适合Notion式块编辑
进阶:可以不使用预设,自己基于Editor基类完全自定义编辑器(框架模式)
三、许可证 & 开源/付费边界(避坑)
- 开源包
ckeditor5:GPL-2.0协议;如果你项目闭源商用分发,GPL会传染,需要购买商业License;内部后台自用很多场景可以GPL,但务必评估法务风险 - 从 v44+ 开始,配置项必须写
licenseKey;免费测试key可以官网申请,生产商用要正式授权 - 区分:免费开源插件 (基础:加粗、标题、表格、图片、链接);Premium付费插件:实时协同、修订模式、批注、Word导入导出、PDF导出、文档大纲、格式刷、AI助手等
四、安装方式(3种主流)
方式1:NPM + Vite/Webpack(推荐,自定义最强)
npm install ckeditor5
最小示例(ClassicEditor)
javascript
import { ClassicEditor, Essentials, Bold, Italic, Paragraph, Heading } from 'ckeditor5';
import 'ckeditor5/ckeditor5.css';
ClassicEditor.create( document.querySelector('#editor'), {
licenseKey: 'your-key',
plugins: [ Essentials, Bold, Italic, Paragraph, Heading ],
toolbar: [ 'bold', 'italic', 'heading' ]
} )
.then( editor => window.editor = editor )
.catch( err => console.error(err) );
Essentials:必须,包含撤销、重做、输入、粘贴基础能力
方式2:CDN(快速演示,不适合深度定制)
全局 CKEDITOR 对象,不用打包,适合简单页面。
方式3:CKEditor Builder(可视化在线构建)
官网在线勾选插件、工具栏,直接下载打包好的js+css,适合不会打包、快速交付。
框架官方集成
React / Vue2 / Vue3 / Angular 都有官方封装包,不要自己手写封装: @ckeditor/ckeditor5-react、@ckeditor/ckeditor5-vue
五、常用配置项详解
javascript
{
// 工具栏
toolbar: {
items: ['bold','italic','link','uploadImage','table','undo','redo'],
shouldNotGroupWhenFull: true // 工具栏放不下自动换行,而不是折叠
},
// 图片上传(核心:自定义上传适配器)
simpleUpload: {
uploadUrl: '/api/upload',
headers: { Authorization: 'Bearer xxx' }
},
// 语言:zh-cn 需要单独引入翻译包
language: 'zh-cn',
// 内容校验、schema扩展
// 编辑器初始内容
initialData: '<p>初始内容</p>',
// 自动保存插件配置
autosave: {
save(editor) {
return fetch('/api/save', {method:'POST', body:editor.getData()})
}
}
}
常用API(拿到editor实例后)
scss
editor.getData() // 获取最终HTML(downcast结果)
editor.setData(html) // 回填HTML,会走upcast解析到model
editor.execute('bold') // 执行命令
editor.model // 访问模型
editor.model.change( writer => {
// 事务,修改model必须包在 change 事务里!
})
editor.on('change:data', ()=>{ /* 内容变更监听 */ })
editor.focus()
editor.destroy() // 销毁编辑器,释放内存
⚠️ 重要:修改Model必须在
editor.model.change( writer => {} )事务中,writer是唯一合法修改器,不能直接改model节点。
六、插件开发(自定义插件核心流程)
插件本质是一个类,实现 Plugin:
javascript
import { Plugin } from 'ckeditor5';
export default class MyPlugin extends Plugin {
static get requires() { return []; } // 依赖其他插件
init() {
const editor = this.editor;
// 1.注册命令
editor.commands.add('myCmd', {
execute() { console.log('执行自定义命令') }
})
// 2.注册UI按钮
editor.ui.componentFactory.add('myBtn', locale => {
const button = new ButtonView(locale);
button.label = '自定义按钮';
button.on('execute', ()=> editor.execute('myCmd'));
return button;
})
}
}
然后加到 plugins 数组,工具栏配置加上 myBtn。
扩展Schema(允许自定义标签/属性)
php
editor.model.schema.register('my-tag', {
inheritAllFrom: '$block',
allowAttributes: ['data-id']
});
// 配置 upcast/downcast 转换规则,实现HTML ↔ model映射
七、图片上传(高频踩坑点)
CKEditor5没有内置上传后端 ,上传逻辑由 UploadAdapter 适配器实现:
- SimpleUploadAdapter:简单单文件上传,直接传FormData
- 自定义Adapter:自己实现
upload()、abort(),对接oss/自研上传接口 - 粘贴图片、拖拽图片都会走适配器> > 坑:很多人直接用富文本插入base64图片,会导致HTML巨大、数据库膨胀,生产禁止。
八、粘贴处理 & 过滤HTML
粘贴流程: 粘贴HTML → upcast → 经过schema校验 → 合法节点进入model;非法标签/属性默认直接丢弃。
- 想保留自定义属性:扩展schema + 增加转换规则
- 想清理Word粘贴垃圾样式:用
PasteFromOffice插件(官方) - 不要用前端正则过滤HTML,优先用CKEditor自身的转换机制,更稳定
九、实时协同(Collaboration)
CKEditor5的架构原生为协同设计,原理: 所有客户端同步Operation原子操作,而不是同步完整HTML;基于OT算法。
- 必须付费Premium服务:CKEditor Cloud Services(官方云协同服务)或者Self-hosted协同服务
- 配套功能:评论、修订模式(Track Changes)、版本历史、@提及> > 自研协同成本极高,不建议自己基于operation写协同。
十、常见坑清单
- ❌ 直接操作编辑器内部DOM:模型和视图不同步,选区错乱、丢失内容
- ❌ 忘记在
model.change事务里修改模型:报错、不生效 - ❌ 混淆 model 和输出HTML:model里没有div、span,是一套独立节点
- ❌ 升级版本后licenseKey报错:v44+强制licenseKey
- ❌ 粘贴Word样式乱:缺少
PasteFromOffice - ❌ 中文不显示:没有引入
zh-cn翻译包 - ❌ 图片跨域、上传回调不处理:上传成功后必须返回
{url:"xxx"} - ❌ 表单提交直接拿内部dom html:一定要用
editor.getData()
十一、和同类编辑器对比
- CKEditor5:可控模型、强插件、成熟协同、企业级文档场景;体积偏大,学习曲线高,商用要注意许可证
- TinyMCE:传统富文本,上手简单,DOM优先
- Quill:轻量、Delta,适合简单协同,复杂文档弱
- WangEditor:国内开源,简单好用,适合国内后台,底层DOM优先