CKEditor5 完整详解

CKEditor5 是从零用TS重写 的现代富文本编辑器框架,不是简单的WYSIWYG,而是一套基于自定义数据模型 + MVC + 虚拟DOM的可扩展编辑引擎,插件化架构,原生支持实时协同;和 CKEditor4 完全不兼容,底层逻辑差异巨大。

一句话重点:CKEditor5 内部有一套独立数据模型,不是直接操作DOM,模型 ↔ 视图 ↔ 输出HTML是三层映射,这是它协同、可控、可校验的根基。

一、核心架构(最重要)

三层分离:Data Model(数据模型) → View(视图) → DOM

  1. 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种开箱即用编辑器,选一个基础模板:

  1. ClassicEditor 经典编辑器(最常用):顶部固定工具栏,下方编辑区,传统表单富文本
  2. InlineEditor 行内编辑器:点击文字直接编辑,无固定工具栏,类似Medium
  3. BalloonEditor 气泡编辑器:选中文字弹出悬浮工具栏(气泡)
  4. 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 适配器实现:

  1. SimpleUploadAdapter:简单单文件上传,直接传FormData
  2. 自定义Adapter:自己实现 upload()、abort(),对接oss/自研上传接口
  3. 粘贴图片、拖拽图片都会走适配器> > 坑:很多人直接用富文本插入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写协同。

十、常见坑清单

  1. ❌ 直接操作编辑器内部DOM:模型和视图不同步,选区错乱、丢失内容
  2. ❌ 忘记在 model.change 事务里修改模型:报错、不生效
  3. ❌ 混淆 model 和输出HTML:model里没有div、span,是一套独立节点
  4. ❌ 升级版本后licenseKey报错:v44+强制licenseKey
  5. ❌ 粘贴Word样式乱:缺少 PasteFromOffice
  6. ❌ 中文不显示:没有引入 zh-cn 翻译包
  7. ❌ 图片跨域、上传回调不处理:上传成功后必须返回 {url:"xxx"}
  8. ❌ 表单提交直接拿内部dom html:一定要用 editor.getData()

十一、和同类编辑器对比

  • CKEditor5:可控模型、强插件、成熟协同、企业级文档场景;体积偏大,学习曲线高,商用要注意许可证
  • TinyMCE:传统富文本,上手简单,DOM优先
  • Quill:轻量、Delta,适合简单协同,复杂文档弱
  • WangEditor:国内开源,简单好用,适合国内后台,底层DOM优先
相关推荐
jerrywus6 分钟前
用 AMD Radeon Cloud 免费跑 ComfyUI:从开机到打开界面
前端·agent·claude
掘金者阿豪16 分钟前
数据库性能优化:一次慢查询背后,可能不只是SQL的问题
前端·后端
AskHarries1 小时前
联盟营销怎么玩
后端
deli0072 小时前
锁过期了业务还没跑完:SETNX 分布式锁 1000 次并发实测
前端
一条Go2 小时前
Webhook 签名:钉钉、企业微信、飞书的四种算法差异
后端·架构·github
不一样的少年_3 小时前
用了这 Skill,我觉得前端兄弟可以毕业了
前端·后端·agent
FRing033 小时前
vue2干货总结10(json-server、vant-ui、postcss插件、axios二次封装、图形验证码、toast轻提示)
开发语言·前端·vue.js·ui·json·vue2·postcss
梦想很大很大3 小时前
一句“你好”用了 5671 Token:我在 Workrun 中追查 Agent 隐性成本的过程
前端·人工智能·后端
坤岭3 小时前
Agentic BI 落地实战
后端