CKEditor 5 与 React 的 CDN 集成指南从组件安装到高级配置【免费下载链接】ckeditor5Powerful rich text editor framework with a modular architecture, modern integrations, and features like collaborative editing.项目地址: https://gitcode.com/GitHub_Trending/ck/ckeditor5CKEditor 5 官方为 React 应用提供了开箱即用的CKEditor组件配合useCKEditorCloud辅助函数可以从 CDN 按需加载编辑器代码与插件无需本地打包ckeditor5依赖。本文完整覆盖 Quick Start、组件全部属性、Context 协作特性、Decoupled/Inline 编辑器特殊用法、本地化与 TypeScript 类型支持并结合本仓库源码说明底层实现原理让你在 React 项目中快速集成并深度定制富文本编辑器。集成方式概览CKEditor 5 官方 React 集成ckeditor/ckeditor5-react包提供CKEditor组件通过 props 传入编辑器构建editor build、配置config和事件处理器。组件支持多种编辑器类型经典编辑器Classic、行内编辑器Inline和解耦编辑器Decoupled即文档编辑器多根Multi-root编辑器请使用专用的 multi-root editor hook。本文示例均基于 CDN 分发方式编辑器核心代码与插件通过useCKEditorCloud从 CDN 动态加载而不是随 React 应用一同打包。这与传统的 npm 安装 本地构建方式不同CDN 方式可以减少应用打包体积编辑器代码独立于业务代码按需加载仅加载需要的插件与语言资源无需手动管理ckeditor5的构建流程。快速开始Quick Start前置条件已有一个可运行的 React 项目若无请参照 React 官方文档创建。同时若需使用 CKEditor 云服务请先创建一个免费账户 并了解许可证密钥激活。安装 React 集成包npm install ckeditor/ckeditor5-react该包提供两个关键导出useCKEditorCloudReact Hook负责从 CDN 加载编辑器代码与插件并返回加载状态与数据CKEditor渲染编辑器实例的 React 组件。创建编辑器组件新建Editor.jsx组件使用useCKEditorCloud加载编辑器代码再交给CKEditor渲染。以下示例同时加载了开源插件与 premium 插件import React from react; import { CKEditor, useCKEditorCloud } from ckeditor/ckeditor5-react; const CKEditorDemo () { const cloud useCKEditorCloud( { version: 45.0.0, premium: true } ); if ( cloud.status error ) { return divError!/div; } if ( cloud.status loading ) { return divLoading.../div; } const { ClassicEditor, Essentials, Paragraph, Bold, Italic } cloud.CKEditor; const { FormatPainter } cloud.CKEditorPremiumFeatures; return ( CKEditor editor{ ClassicEditor } data{ pHello world!/p } config{ { licenseKey: YOUR_LICENSE_KEY, plugins: [ Essentials, Paragraph, Bold, Italic, FormatPainter ], toolbar: [ undo, redo, |, bold, italic, |, formatPainter ] } } / ); };要点说明version指定要加载的 CKEditor 5 版本号应替换为你实际使用的版本premium: true时额外的加载 premium 插件资源会有额外的网络请求仅在需要时开启cloud.status有三种状态loading、error和加载完成后的ready据此渲染加载提示或错误提示编辑器类与插件从cloud.CKEditor基础库和cloud.CKEditorPremiumFeaturespremium 功能中解构。useCKEditorCloud底层原理useCKEditorCloud是 CDN 资源加载指南 中loadCKEditorCloud函数针对 React 框架的包装。loadCKEditorCloud来自ckeditor/ckeditor5-integrations-common包其职责包括自动向页面head注入所需的script与link标签确保同一资源只加载一次避免重复注入返回 Promise解析为包含各 CDN 资源导出数据的对象。loadCKEditorCloud与useCKEditorCloud接受的配置项完全一致选项必填类型说明version是string要加载的 CKEditor 5 版本号premium为true时同时决定 premium 功能版本translations否string[]需要加载翻译的语言代码数组premium否boolean是否加载 premium 插件ckbox否objectCKBox 集成加载配置version、themeplugins否object额外插件加载配置键为全局插件名值为插件配置injectedHtmlElementsAttributes否object注入script/link标签时附加的属性默认{ crossorigin: anonymous }可用于添加integrity等属性其中plugins配置支持三种形式字符串数组URL 列表、动态import()函数、或包含scripts、stylesheets与可选checkPluginLoaded回调的对象。若不提供checkPluginLoaded插件对象键必须与插件暴露的全局对象名一致。组件属性详解CKEditor组件支持的属性如下属性必填类型说明editor是Editor构造器使用的编辑器构造类如ClassicEditor、InlineEditor、DecoupledEditordata否string编辑器初始数据详见获取与设置数据config否object编辑器配置详见配置指南id否string编辑器 ID该属性变化时组件会用新数据重启编辑器而不是在已初始化的编辑器上 setDatadisabled否boolean为true时编辑器切换为只读模式disableWatchdog否boolean为true时禁用看门狗watchdog功能默认falsewatchdogConfig否object看门狗功能配置对象onReady否function编辑器就绪时回调参数为Editor实例组件因错误重新初始化后也会调用onAfterDestroy否function编辑器实例成功销毁后回调组件因错误重新初始化后也会触发。注意调用时组件可能已卸载onChange否function编辑器数据变化时回调onBlur否function编辑器失焦时回调onFocus否function编辑器获得焦点时回调onError否function编辑器初始化或运行期间崩溃时回调接收两个参数错误实例与错误详情事件回调onChange、onBlur、onFocus接收两个参数EventInfo对象——来自 utils 包的 EventInfo 类封装了事件名、源对象等基础信息Editor实例——即 core 包的 Editor 基类所有编辑器类型Classic/Inline/Balloon/Decoupled都继承自它通过该实例可以访问model、editing、ui等核心子系统。onError的错误详情对象包含两个属性phase:initialization | runtime—— 指明错误发生在初始化期间还是运行期间willEditorRestart—— 为true时表示组件将自动重启编辑器。Context 特性多编辑器共享上下文ckeditor/ckeditor5-react还提供CKEditorContext组件用于承载 context 特性配合部分协作功能使用。import React from react; import { CKEditor, CKEditorContext, useCKEditorCloud } from ckeditor/ckeditor5-react; export const CKEditorCloudContextDemo () { const cloud useCKEditorCloud( { version: 45.0.0 } ); if ( cloud.status error ) { return divError!/div; } if ( cloud.status loading ) { return divLoading.../div; } const { ClassicEditor } cloud.CKEditor; return ( CKEditorContext context{ ClassicEditor.Context } contextWatchdog{ ClassicEditor.ContextWatchdog } onChangeInitializedEditors{ editors { console.log( Initialized editors:, editors ); } } CKEditorNestedInstanceDemo nameeditor1 contentpEditor 1/p / br / CKEditorNestedInstanceDemo nameeditor2 contentpEditor 2/p / /CKEditorContext ); }; function CKEditorNestedInstanceDemo( { name, content } ) { const cloud useCKEditorCloud( { version: 45.0.0, premium: true } ); if ( cloud.status error ) { console.error( cloud ); return divError!/div; } if ( cloud.status loading ) { return divLoading.../div; } const { ClassicEditor, Essentials, Paragraph, Bold, Italic, Mention } cloud.CKEditor; return ( CKEditor contextItemMetadata{ { name } } editor{ ClassicEditor } data{ content } config{ { plugins: [ Essentials, Paragraph, Bold, Italic, Mention ], toolbar: { items: [ undo, redo, |, bold, italic ], } } } / ); }CKEditorContext组件属性属性必填类型说明context是Context 类CKEditor 5 上下文类即 core 包的 Context 类对应ClassicEditor.ContextcontextWatchdog是Watchdog context 类看门狗上下文类即 watchdog 包的 ContextWatchdog 类对应ClassicEditor.ContextWatchdogconfig否objectCKEditor 5 上下文配置isLayoutReady否boolean为false时延迟上下文创建变为true或取消设置时才创建上下文及其子编辑器。使用 annotations 或 presence list 等需要布局的功能时很有用id否string上下文 ID变化时组件会重启上下文及其编辑器并基于当前配置重新初始化onChangeInitializedEditors否function树中任一编辑器初始化或销毁时调用参数为已初始化编辑器的字典键为CKEditor组件上contextItemMetadata.name的值未设置contextItemMetadata时使用编辑器 IDonReady否function上下文就绪且所有子编辑器已初始化时调用参数为context实例错误后重新初始化也会调用onError否function上下文初始化或运行期间崩溃时回调错误详情包含phaseinitialization | runtime与willContextRestart为true表示组件将自动重启Context.create()静态工厂方法负责上下文实例的创建与插件初始化见 Context.create。协作场景下上下文让多个编辑器实例共享同一批协作服务与插件。实战使用文档Decoupled编辑器类型解耦编辑器DecoupledEditor的工具条与编辑区是分离的工具条不会自动插入 DOM需要手动挂载到页面中对应DecoupledEditor.create的返回值结构与经典编辑器不同工具条元素位于editor.ui.view.toolbar.element。import { useEffect, useRef, useState } from react; import { CKEditor } from ckeditor/ckeditor5-react; function App() { const cloud useCKEditorCloud( { version: 45.0.0 } ); const editorToolbarRef useRef( null ); const [ isMounted, setMounted ] useState( false ); useEffect( () { setMounted( true ); return () { setMounted( false ); }; }, [] ); if ( cloud.status error ) { console.error( cloud ); return divError!/div; } if ( cloud.status loading ) { return divLoading.../div; } const { DecoupledEditor, Essentials, Paragraph, Bold, Italic } cloud.CKEditor; return ( div div ref{ editorToolbarRef }/div div { isMounted ( CKEditor editor{ DecoupledEditor } datapHello from CKEditor 5 decoupled editor!/p config{ { plugins: [ Essentials, Paragraph, Bold, Italic ], toolbar: [ undo, redo, |, bold, italic ] } } onReady{ ( editor ) { if ( editorToolbarRef.current ) { editorToolbarRef.current.appendChild( editor.ui.view.toolbar.element ); } }} onAfterDestroy{ ( editor ) { if ( editorToolbarRef.current ) { Array.from( editorToolbarRef.current.children ).forEach( child child.remove() ); } } } / ) } /div /div ); } export default App;实现要点onReady中将editor.ui.view.toolbar.element追加到页面预留的工具栏容器中onAfterDestroy中清理容器内由编辑器插入的子元素避免销毁后残留 DOM通过isMounted状态确保仅在组件挂载后才创建编辑器。DecoupledEditor 的实现见 decouplededitor.ts其 UI 组件DecoupledEditorUI负责将工具条与编辑区作为独立节点渲染详见 decouplededitorui.ts这正是需要手动挂载工具条的源码依据。实战使用行内编辑器类型InlineEditor、BalloonEditor、DecoupledEditor等单根编辑器可以通过root.modelElement: $inlineRoot配置为仅接受行内内容的行内编辑器只允许文本、加粗、斜体、链接等行内内容不允许块级元素非常适合标题、副标题、单行输入等短文本字段。相关配置项定义在 editorconfig.ts 的 RootConfig 中。import React from react; import { CKEditor, useCKEditorCloud } from ckeditor/ckeditor5-react; const InlineTitleDemo () { const cloud useCKEditorCloud( { version: 45.0.0 } ); if ( cloud.status error ) { return divError!/div; } if ( cloud.status loading ) { return divLoading.../div; } const { BalloonEditor, Essentials, Bold, Italic } cloud.CKEditor; return ( CKEditor editor{ BalloonEditor } config{ { licenseKey: YOUR_LICENSE_KEY, plugins: [ Essentials, Bold, Italic ], toolbar: [ bold, italic ], root: { element: h1, modelElement: $inlineRoot, initialData: Document title, placeholder: Enter title... } } } / ); };root.element属性取值root.element接受两种形式标签名字符串例如h1或section描述对象包含name、classes、styles、attributes字段。需要注意如果只设置root.element而不设置modelElement: $inlineRoot只会改变宿主标签模型层 schema 仍允许块级内容默认根类型为$root接受段落、标题、列表、表格等块级内容。ClassicEditor 的特殊限制CKEditor组件对ClassicEditor始终渲染div宿主root.element不会生效——经典编辑器会自行包裹工具条与编辑区。若要控制宿主元素请使用InlineEditor、BalloonEditor或DecoupledEditor。相关编辑器类型实现分别见 inlineeditor.ts、ballooneditor.ts 与 classiceditor.ts。关于根类型的完整技术说明$root与$inlineRoot的允许内容对比、多根编辑器混合根类型、宿主元素样式定制等可参考 根类型指南 与编辑器类型指南。与协作插件配合使用官方提供了可直接使用的 React 协作编辑示例real-time collaboration for React。虽然不是强制要求基于该示例构建应用但它能帮助你快速起步。协作功能通常与上述CKEditorContext组件配合使用在真实协作场景中还需结合 context 与协作特性文档 了解 annotations、presence list、track changes 等能力的上下文依赖。本地化LocalizationCKEditor 5 支持多种 UI 语言官方 React 组件同样支持。只需在useCKEditorCloud配置的translations数组中传入需要的语言代码即可import React from react; import { CKEditor, useCKEditorCloud } from ckeditor/ckeditor5-react; const CKEditorDemo () { const cloud useCKEditorCloud( { version: 45.0.0, translations: [ es ] } ); if ( cloud.status error ) { return divError!/div; } if ( cloud.status loading ) { return divLoading.../div; } const { ClassicEditor, Essentials, Bold, Italic, Paragraph } cloud.CKEditor; return ( CKEditor editor{ ClassicEditor } data{ pHello world!/p } config{ { licenseKey: YOUR_LICENSE_KEY, toolbar: [ undo, redo, |, bold, italic ], plugins: [ Bold, Essentials, Italic, Paragraph ], } } / ); };translations数组对应 CDN 加载配置中的翻译资源具体实现细节见 加载 CDN 资源指南 与 设置 UI 语言指南。注意 translations 中指定的语言会以额外网络请求的形式加载仅列出实际需要的语言即可。TypeScript 支持官方 React 集成本身由 TypeScript 编写天然支持 TS 项目CKEditor组件无需额外配置即可获得类型提示。如需使用 CKEditor 5 包中的特定类型可从专门的类型定义模块导入import React from react; import { CKEditor, useCKEditorCloud } from ckeditor/ckeditor5-react; import type { EventInfo } from https://cdn.ckeditor.com/typings/ckeditor5.d.ts; const CKEditorDemo () { const cloud useCKEditorCloud( { version: 45.0.0, translations: [ es ] } ); if ( cloud.status error ) { return divError!/div; } if ( cloud.status loading ) { return divLoading.../div; } const { ClassicEditor, Essentials, Bold, Italic, Paragraph } cloud.CKEditor; return ( CKEditor editor{ ClassicEditor } data{ pHello world!/p } config{ { licenseKey: YOUR_LICENSE_KEY, toolbar: [ undo, redo, |, bold, italic ], plugins: [ Bold, Essentials, Italic, Paragraph ], } } onBlur{ ( event: EventInfo ) { // your event handler } } / ); };说明https://cdn.ckeditor.com/typings/ckeditor5.d.ts并非真实的类型文件 URL而是一个合成 TypeScript 模块为编辑器提供类型定义实际的类型由ckeditor5包提供该包类型依赖于ckeditor/ckeditor5-react该方案能避免用户直接从ckeditor5包导入任何代码从而防止代码重复打包问题。Premium 功能的类型定义如需使用 premium 功能的类型需先安装ckeditor5-premium-features包npm install --save-dev ckeditor5-premium-features之后即可像基础编辑器类型一样导入 premium 类型script setup // ... import type { Mention } from https://cdn.ckeditor.com/typings/ckeditor5-premium-features.d.ts; // ... /script已知问题与排查基础编辑器的类型定义通常开箱即用但部分打包器不会安装提供类型支持的ckeditor5包。若遇到类型定义缺失的问题可手动安装npm install --save-dev ckeditor5后续学习路径了解如何操作编辑器数据获取与设置数据进一步定制编辑器配置指南了解具体功能特性功能特性索引加载 CDN 资源的完整选项加载 CDN 资源多根编辑器集成React Multi-root CDN 集成。【免费下载链接】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），仅供参考