CKEditor 5 编辑器类型完全指南Classic、Inline、Balloon、Decoupled 与 Multi-root 的选型与实战【免费下载链接】ckeditor5Powerful rich text editor framework with a modular architecture, modern integrations, and features like collaborative editing.项目地址: https://gitcode.com/GitHub_Trending/ck/ckeditor5CKEditor 5 提供了六种开箱即用的编辑器类型Classic、Inline、Balloon、Balloon Block、Decoupled/Document、Multi-root它们在用户界面、编辑交互方式上各有差异某些功能如块级工具栏、多可编辑区域仅特定类型可用。本文以 docs/getting-started/setup/editor-types.md 为主线逐类讲解每种编辑器类型的适用场景、初始化代码与底层实现并给出按场景选型的建议帮助你在实际项目中快速做出正确选择并完成集成。概述六种类型共享同一套架构所有编辑器类型都从主包ckeditor5中导入导入方式与导入功能插件如Essentials、Bold完全一致详见 快速入门指南。也就是说你只需要替换导入的编辑器类名其余配置插件、工具栏、语言等的写法保持一致。从源码结构看这六种类型分别对应独立包中的独立实现类编辑器类型实现类源码位置ClassicClassicEditorpackages/ckeditor5-editor-classic/src/classiceditor.tsInlineInlineEditorpackages/ckeditor5-editor-inline/src/inlineeditor.tsBalloonBalloonEditorpackages/ckeditor5-editor-balloon/src/ballooneditor.tsDecoupledDecoupledEditorpackages/ckeditor5-editor-decoupled/src/decouplededitor.tsMulti-rootMultiRootEditorpackages/ckeditor5-editor-multi-root/src/multirooteditor.ts如果你不确定该选哪种类型可以借助 CKEditor 5 Builder 快速预览和试验不同预设再回到文档中落地配置。另外以上六种类型之外你还可以使用 CKEditor 5 Framework 基于 文档框架指南 自行定制专属的编辑器类型。提示ClassicEditor目前同时支持新式的create( { attachTo: ... } )配置对象签名和旧式的create( element, config )签名后者已标记为废弃deprecated。如果你在代码库中看到create( document.querySelector( #editor ) )的写法建议逐步迁移到新的配置对象签名。Classic editor最传统的所见即所得形态Classic editor 是大多数用户对富文本编辑器最传统的认知形态——页面上一个固定位置的编辑区域配合工具栏通常作为表单的一部分用于向服务器提交内容。源码定位packages/ckeditor5-editor-classic/src/classiceditor.ts在线示例classic-editor 示例初始化代码import { ClassicEditor, Essentials, Bold, Italic, Font, Paragraph } from ckeditor5; ClassicEditor .create( { attachTo: document.querySelector( #editor ), licenseKey: YOUR_LICENSE_KEY, plugins: [ Essentials, Bold, Italic, Font, Paragraph ], toolbar: [ bold, italic ] } ) .then( editor { console.log( The classic editor initialized, editor ); } ) .catch( error { console.error( error ); } );从源码理解其内部结构从 classiceditor.ts 的实现可以看出 Classic editor 的三个关键特性替换式初始化传入的#editor元素内容会被作为编辑器的初始数据编辑器初始化完成后会将该元素替换为编辑器 UI源码中通过normalizeRootsConfig()将元素规范化到roots.main.element并调用attachToForm()与原生表单建立关联。如果传入的元素未连接到 DOM!sourceElement.isConnected会抛出editor-source-element-not-attached错误。三种初始化方式create()支持三种形态——替换已有 DOM 元素元素内容作为初始数据、传入初始数据字符串创建游离detached编辑器此时需手动document.body.appendChild( editor.ui.element )插入 DOM、或两者混合元素 root.initialData配置。文档中混用initialData与元素时会覆盖元素原有内容。内建盒式 UIClassicEditorUIView使用sticky toolbar inline editable的组合整体包裹在带边框的盒式界面中工具栏在空间不足时会自动分组折叠shouldToolbarGroupWhenFull可通过toolbar.shouldNotGroupWhenFull关闭。此外Classic editor 与textarea及原生表单深度集成若配置updateSourceElementOnDestroy: true编辑器销毁或所属表单提交时内容会回写回原始元素保证传统服务端表单提交场景无缝工作。Inline editor就地编辑你的页面内容Inline editor 自带一个浮动工具栏floating toolbar只有当编辑器获得焦点例如点击编辑区域时工具栏才会显示。它的典型使用场景是让用户在网页的真实位置上直接编辑内容如标题、段落等小区域而不是跳转到独立的后台管理区。源码定位packages/ckeditor5-editor-inline/src/inlineeditor.ts在线示例inline-editor 示例初始化代码import { InlineEditor, Essentials, Bold, Italic, Font, Paragraph } from ckeditor5; InlineEditor .create( { root: { element: document.querySelector( #editor ) }, licenseKey: YOUR_LICENSE_KEY, plugins: [ Essentials, Bold, Italic, Font, Paragraph ], toolbar: [ bold, italic ] } ) .then( editor { console.log( The inline editor initialized, editor ); } ) .catch( error { console.error( error ); } );与 Classic 的关键差异从 inlineeditor.ts 可以看到传入的元素不会被替换而是直接变成可编辑区域editable element。源码中通过secureSourceElement()对源元素做了保护处理。不存在盒式 UI工具栏以InlineEditorUIView的浮动形式渲染跟随编辑器焦点出现。数据回写行为不同destroy()时先缓存数据再销毁getData()随后才updateSourceElement( data )写回源元素。Balloon editor 与 Balloon block editorMedium 风格的工具条Balloon editor 与 Inline editor 非常相似核心区别在于工具栏的呈现方式Balloon editor 的工具栏以**气泡balloon**的形式出现在选区旁边当选区非空时出现类似 Medium 等现代编辑体验。源码定位packages/ckeditor5-editor-balloon/src/ballooneditor.ts在线示例balloon-editor 示例Balloon block editor附加块级工具栏Balloon block editor 本质上是 Balloon editor 加一个额外的块级工具栏block toolbar可编辑内容区旁边有一个按钮点击后出现跟随文档选区移动的工具栏用于访问额外的块级编辑功能如段落样式、标题级别等。在线示例balloon-block-editor 示例初始化代码import { BalloonEditor, Essentials, Bold, Italic, Font, Paragraph } from ckeditor5; BalloonEditor .create( { root: { element: document.querySelector( #editor ) }, licenseKey: YOUR_LICENSE_KEY, plugins: [ Essentials, Bold, Italic, Font, Paragraph ], toolbar: [ bold, italic ], // The optional setting configures the side toolbar. blockToolbar: [ paragraph, heading1, heading2, heading3 ] } ) .then( editor { console.log( The balloon editor initialized, editor ); } ) .catch( error { console.error( error ); } );源码中的自动装配逻辑从 ballooneditor.ts 可以看到一个值得注意的实现细节BalloonEditor 的构造函数会自动把BalloonToolbar插件追加进plugins配置plugins.push( BalloonToolbar )并把toolbar配置复制为balloonToolbar配置this.config.define( balloonToolbar, this.config.get( toolbar ) )。也就是说你配置的toolbar: [ bold, italic ]在 Balloon editor 中会被用作气泡工具栏的内容。BalloonToolbar本身位于 UI 包中定义在 packages/ckeditor5-ui/src/toolbar/balloon/balloontoolbar.ts其行为显示时机、定位可以参考 toolbar 配置指南 中关于 block toolbar 的说明。Decoupled editorDocument editor工具栏与编辑区彻底分离Decoupled editor 的名字源于其独特的结构——工具栏和编辑区域是彼此独立的元素。这种设计带来更大的灵活性与定制空间适用于远超传统所见即所得编辑器的各类应用。它最流行的用法是文档编辑器document editor类似 Google Docs、Microsoft Word 等大型编辑套件的体验非常适合创作后续要打印或导出为 PDF 的文档。由于工具栏与编辑区分离你可以把编辑器集成到应用的不同位置或自由定制其外观与功能。例如创建一个把工具栏放在编辑区底部的邮件创作器仓库中提供了可运行的示例bottom-toolbar-editor 示例。源码定位packages/ckeditor5-editor-decoupled/src/decouplededitor.ts在线示例document-editor 示例初始化代码import { DecoupledEditor, Essentials, Bold, Italic, Font, Paragraph } from ckeditor5; DecoupledEditor .create( { root: { element: document.querySelector( #editor ) }, licenseKey: YOUR_LICENSE_KEY, plugins: [ Essentials, Bold, Italic, Font, Paragraph ], toolbar: [ undo, redo, |, bold, italic, |, fontSize, fontFamily, fontColor, fontBackgroundColor ] } ) .then( editor { console.log( The decoupled editor initialized, editor ); } ) .catch( error { console.error( error ); } );关键手动挂载工具栏与编辑区与其他类型最大的不同是——Decoupled editor 默认不会把工具栏渲染到页面 DOM 中的任何位置需要你初始化后手动挂载DecoupledEditor .create( { root: { element: document.querySelector( #editor ) } } ) .then( editor { // Append the toolbar to the body element. document.body.appendChild( editor.ui.view.toolbar.element ); } ) .catch( err { console.error( err.stack ); } );如果使用游离方式初始化只传root.initialData则编辑区元素也需要手动挂载通过editor.ui.getEditableElement()获取。销毁时同理Decoupled editor不会自动移除工具栏和编辑区需要在destroy()之后自行清理editor.destroy() .then( () { // Remove the toolbar from DOM. editor.ui.view.toolbar.element.remove(); // Remove the editable from DOM. editor.ui.view.editable.element.remove(); console.log( Editor was destroyed ); } );Multi-root editor一个实例管理多个可编辑区域Multi-root editor 拥有多个彼此分离的可编辑区域roots。它与多个独立编辑器的本质区别在于同一实例下的所有可编辑区域共享同一份配置、同一条工具栏和同一个撤销栈它们共同构成一份文档。源码定位packages/ckeditor5-editor-multi-root/src/multirooteditor.ts在线示例multi-root-editor 示例注意目前 Multi-root editor 尚不能通过 CKEditor 5 Builder 生成且它需要更高级的 roots 配置。初始化代码在create()中一次性传入所有需要的 rootsimport { MultiRootEditor, Essentials, Bold, Italic, Font, Paragraph } from ckeditor5; MultiRootEditor .create( { roots: { header: { element: document.querySelector( #header ) }, content: { element: document.querySelector( #content ) }, leftSide: { element: document.querySelector( #left-side ) }, rightSide: { element: document.querySelector( #right-side ) } }, licenseKey: YOUR_LICENSE_KEY, plugins: [ Essentials, Bold, Italic, Font, Paragraph ], toolbar: [ undo, redo, |, bold, italic, |, fontSize, fontFamily, fontColor, fontBackgroundColor ] } ) .then( /* ... */ ) .catch( /* ... */ );随后在文档中使用这些 roots 的 id 放置编辑器区域div classeditor div idheader Header content. /div /div div classeditor div idcontent Main content. /div /div div classboxes div classbox box-left editor div idleft-side Left side content. /div /div div classbox box-right editor div idright-side Right side content. /div /div /div源码中的单实例多根语义从 multirooteditor.ts 的实现注释可以确认其设计定位一个编辑器实例控制多个 inline 可编辑元素它们共享同一份配置、文档 ID 与撤销栈。这也是 Multi-root 与部署多个独立 Inline editor 之间的关键差异——多根情况下各区域的编辑操作是相互关联的例如撤销操作可以跨区域生效并统一作为一个整体文档输出。与 Decoupled editor 类似Multi-root editor 的工具栏也需要你在初始化后手动挂载到页面指定位置。进阶为 root 限定内容类型所有编辑器类型都支持配置某个 root 能容纳什么内容这在 Multi-root 场景下最有用但对任何编辑器类型都生效。例如你可以在多根编辑器中让headerroot 只接受标题、contentroot 只接受段落从而约束每个区域的语义结构。详细配置方法参见 Root types 指南。选型速查与常见误区需求场景推荐类型关键原因传统表单/后台内容管理编辑区固定Classic替换式渲染与表单提交天然集成在页面原地编辑标题、段落等小区域Inline不替换元素元素即编辑区Medium 风格的选中即弹工具条Balloon气泡工具条跟随选区需要块级样式工具标题、段落格式Balloon Block多一个跟随选区的块级工具条邮件编辑器、文档编辑器、自由布局工具栏Decoupled工具栏与编辑区完全分离可任意摆放页面含多个相互关联的编辑区Multi-root共享配置、工具栏与撤销栈输出为一份文档常见误区提醒Inline/Balloon 不会替换源元素元素本身就是编辑区而 Classic 会替换源元素。Decoupled 与 Multi-root 的工具栏需要手动挂载否则初始化后看不到工具栏。Balloon 的气泡工具栏内容来自toolbar配置源码自动将toolbar复制为balloonToolbar新增的blockToolbar才是可选块级工具条。如果内容要提交到传统formClassic editor 配合updateSourceElementOnDestroy是最省心的选择。进一步阅读编辑器配置全量说明EditorConfig 配置文档工具栏配置含 block toolbar 行为toolbar 配置指南为每个 root 限定内容类型Root types 指南六种类型的在线示例目录docs/examples/builds自定义编辑器类型CKEditor 5 Framework 外部 UI 指南【免费下载链接】ckeditor5Powerful rich text editor framework with a modular architecture, modern integrations, and features like collaborative editing.项目地址: https://gitcode.com/GitHub_Trending/ck/ckeditor5创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
