在 Electron 桌面应用中集成 CKEditor 5（ZIP 自托管方案）完整指南-平芜编程栈

在 Electron 桌面应用中集成 CKEditor 5（ZIP 自托管方案）完整指南

【免费下载链接】ckeditor5Powerful rich text editor framework with a modular architecture, modern integrations, and features like collaborative editing.项目地址: https://gitcode.com/GitHub_Trending/ck/ckeditor5

CKEditor 5 是模块化架构的富文本编辑器框架，其渲染层基于浏览器原生能力构建。由于 Electron 窗口由 Chromium 内核渲染，CKEditor 5 的 HTML 编辑器可以像运行在网页中一样运行在 Electron 的渲染进程（renderer process）里。本指南将带你使用「Online Builder 生成的自定义构建 + ZIP 自托管包」的方式，把 CKEditor 5 集成进一个 Electron 桌面应用，涵盖项目搭建、ZIP 包准备、编辑器初始化、许可证激活等完整流程。读完本文，你将能够在 Electron 应用中快速落地一个带工具栏、可扩展插件的所见即所得编辑器。

本文对应的完整参考文档位于 docs/getting-started/integrations/electron.md，并辅以仓库中相关源码与配置佐证。

为什么可以这样集成

Electron 应用的主进程（main process）负责创建窗口，而每个窗口中的页面内容由渲染进程加载。因为渲染进程运行的就是 Chromium 渲染引擎，CKEditor 5 的编辑视图、交互逻辑与浏览器环境完全一致——不需要任何原生（native）适配层，直接把网页版编辑器资源加载进来即可工作。

本文采用ZIP 自托管方案，即把编辑器构建产物以静态文件形式打包进 Electron 应用目录。其核心优势是：

无需 npm 构建链，解压即用；
不依赖 CDN，可在离线环境运行，也便于版本锁定；
与 CDN 方案相比，所有资源随应用本地分发，加载稳定。

（如需 CDN 方式，可参考 docs/getting-started/integrations-cdn/electron.md，集成思路一致，仅资源引入方式不同。）

快速开始：搭建 Electron 项目

如果你对 Electron 尚不熟悉，建议先阅读其官方入门教程了解基础概念。最快的建项目方式是使用 Electron Forge 的脚手架命令：

npx create-electron-app@latest my-app

执行时，CLI 会提示你选择打包器（bundler）和语言。本教程选用Vite + 原生 JavaScript（vanilla JavaScript）组合。脚手架完成后进入项目目录并启动：

cd my-app npm start

此时应该能看到一个默认的 Electron 窗口打开，说明项目搭建成功。

准备 CKEditor 5 的 ZIP 包

在 Electron 中使用的编辑器需要一个自定义构建（custom build），而最省事的制作方式就是 CKEditor 5 Online Builder。

打开 CKEditor 5 Online Builder；
通过图形化界面选择所需的插件（features）与工具栏布局，无需手写任何配置代码；
在最后一步选择技术与集成方式："Vanilla JavaScript"和"Self-hosted (ZIP)"；
下载生成的 ZIP 归档。

下载的 ZIP 包已包含集成所需的全部文件：主 JavaScript 文件、样式表（CSS）、以及示例实现代码。该包开箱即用，无需任何额外的构建步骤。拿到包后，将其解压（本文示例中解压目录名为ckeditor5-builder）放入 Electron 应用主目录即可。

说明：ZIP 方案属于自托管（self-hosted）分发方式。与 npm 安装方式一致，自托管分发要求配置licenseKey：要么遵循 GPL 协议，要么购买自托管商业许可（详见下文「获取许可证」章节）。仓库中 docs/getting-started/integrations/quick-start.md 对 ZIP 包内的文件构成有更细致的说明。

项目结构一览

完成上述步骤后，应用目录结构应类似：

├── ckeditor5-builder # 从 Online Builder 解压出的编辑器资源目录 ├── forge.config.js ├── index.html ├── node_modules/ ├── package-lock.json ├── package.json ├── src/ │ ├── index.css │ ├── main.js # Electron 主进程 │ ├── preload.js # 预加载脚本 │ └── renderer.js # 渲染进程入口 ├── vite.main.config.mjs ├── vite.preload.config.mjs └── vite.renderer.config.mjs

其中ckeditor5-builder即 Online Builder 下载并解压后的文件夹。主进程（src/main.js）、预加载脚本（src/preload.js）与渲染进程（src/renderer.js）由 Electron Forge 脚手架生成，保持默认即可，我们的集成工作集中在index.html与新增的src/editor.js上。

实现编辑器

1. 创建`src/editor.js`

在src/目录下新建editor.js，内容如下：

const { ClassicEditor, Essentials, Bold, Italic, Font, Paragraph } = CKEDITOR; const { FormatPainter } = CKEDITOR_PREMIUM_FEATURES; ClassicEditor .create( { attachTo: document.querySelector( '#editor' ), licenseKey: '<YOUR_LICENSE_KEY>', plugins: [ Essentials, Bold, Italic, Font, Paragraph, FormatPainter ], toolbar: [ 'undo', 'redo', '|', 'bold', 'italic', '|', 'fontSize', 'fontFamily', 'fontColor', 'fontBackgroundColor', '|', 'formatPainter' ] } ) .then( /* ... */ ) .catch( /* ... */ );

这段代码的关键点：

CKEDITOR与CKEDITOR_PREMIUM_FEATURES是全局命名空间：它们由后续在 HTML 中引入的两个 UMD 构建文件提供（ckeditor5.umd.js与ckeditor5-premium-features.umd.js），无需 import 语句；
plugins数组：传入要加载的插件类。Essentials是必备的核心编辑插件（包含撤销、剪贴板等基础能力），Bold、Italic、Font、Paragraph分别提供加粗、斜体、字体（字号/字族/颜色/背景色）与段落功能；FormatPainter是 premium 功能中的格式刷插件；
toolbar数组：按顺序声明工具栏按钮，'|'表示分组分隔符，'undo'/'redo'对应撤销/重做；
licenseKey：激活编辑器的许可证密钥，必须按实际值替换<YOUR_LICENSE_KEY>；
attachTo：指定编辑器挂载的 DOM 元素（即index.html中的#editor容器）。

该配置对应仓库中的EditorConfig类型定义（见 packages/ckeditor5-core/src/editor/editorconfig.ts），licenseKey、plugins、toolbar等均为标准配置项，对所有编辑器类型（Classic、Inline、Decoupled 等）通用。

2. 修改`index.html`

将脚手架生成的index.html调整为：

<!doctype html> <html> <head> <meta charset="UTF-8" /> <title>Hello World!</title> <link rel="stylesheet" href="./ckeditor5-builder/ckeditor5/ckeditor5.css"> <link rel="stylesheet" href="./ckeditor5-builder/ckeditor5-premium-features/ckeditor5-premium-features.css"> </head> <body> <h1>Hello Electron and CKEditor 5!</h1> <p>Welcome to your Electron application. Below you should see a working instance of CKEditor 5:</p> <div id="editor"></div> <script src="./ckeditor5-builder/ckeditor5/ckeditor5.umd.js"></script> <script src="./ckeditor5-builder/ckeditor5-premium-features/ckeditor5-premium-features.umd.js"></script> <script src="./src/editor.js"></script> <script type="module" src="/src/renderer.js"></script> </body> </html>

各引入资源的职责如下：

资源	作用
`ckeditor5.css`	编辑器基础 UI 与内容样式
`ckeditor5-premium-features.css`	premium 功能的样式（如格式刷）
`ckeditor5.umd.js`	CKEditor 5 的 UMD 构建，暴露全局`CKEDITOR`对象
`ckeditor5-premium-features.umd.js`	premium 功能 UMD 构建，暴露全局`CKEDITOR_PREMIUM_FEATURES`对象
`src/editor.js`	负责把上述资源串联起来并初始化编辑器实例
`src/renderer.js`	Electron 渲染进程脚本（保持脚手架默认）

需要注意脚本引入的顺序：必须先加载 UMD 构建文件，再加载依赖它们的editor.js。

3. 运行应用

一切就绪后执行：

npm start

Electron 会自动打开一个窗口，其中即包含一个可用的 CKEditor 5 实例（效果如上文配图所示）。由于资源从本地目录加载，即使断网也能正常运行。

获取 premium 功能的许可证密钥

示例中使用了FormatPainter（格式刷）这一 premium 功能，因此必须使用商业许可证激活：

免费试用：注册 CKEditor Premium Features 14 天免费试用是最快的体验方式；
商业采购：可联系销售团队获取定制化报价。

拿到激活密钥后，将其填入editor.js的licenseKey配置项即可。完整流程（账户创建、Customer Portal 登录、License keys 区获取密钥、密钥类型说明）参见 docs/getting-started/licensing/license-key-and-activation.md。

这里补充几点与 Electron 自托管场景强相关的许可证要点（依据上述授权文档）：

'GPL'密钥仅适用于自托管分发（npm 或 ZIP 下载），Cloud CDN 分发不接受'GPL'密钥。ZIP 自托管方案正好符合此条件——如果你的项目满足 GPL 合规要求且不包含 premium 功能，可直接在licenseKey中写'GPL'；
开发环境密钥：若使用开发（Development）类型密钥，编辑器运行时会显示开发用途横幅，且仅限localhost、127.0.0.1、192.168.*.*等本地域使用，不得用于生产；
生产密钥：无功能限制；可选配 "Approved hosts" 白名单（最多 5 个域名/IP），进一步防止密钥被未授权使用。

在 Electron 中读写编辑器内容

编辑器初始化完成后，与数据交互的标准方式是getData()与setData()（详见 docs/getting-started/setup/getting-and-setting-data.md）：

// 保存编辑器引用（放在 create().then() 回调之外） let editor; ClassicEditor .create( { attachTo: document.querySelector( '#editor' ), licenseKey: '<YOUR_LICENSE_KEY>', // Or 'GPL'. plugins: [ /* ... */ ], toolbar: [ /* ... */ ] } ) .then( newEditor => { editor = newEditor; } ) .catch( error => { console.error( error ); } ); // 例如：点击按钮时把 HTML 数据发送到本地/远程 document.querySelector( '#save' ).addEventListener( 'click', () => { const data = editor.getData(); // 持久化 data（写入本地文件、调用后端接口等） } ); // 需要时替换整个内容 editor.setData( '<p>Some text.</p>' );

getData()/setData()是Editor基类提供的方法（源码见 packages/ckeditor5-core/src/editor/editor.ts），对所有编辑器类型一致。在 Electron 场景中，你可以把getData()返回的 HTML 通过ipcRenderer发给主进程，再用 Node.js 的fs模块写盘，即可实现本地文档的保存能力。

进阶：继续定制与学习

数据读写进阶：root.initialData初始化数据、editor.getData()选项参数、HTML 表单自动同步等，见获取与设置数据；
编辑器配置：插件安装、工具栏定制、licenseKey等更多配置项，见配置指南；
功能探索：图片、表格、列表、协作等各功能的详细用法，见功能文档总览；
许可证与激活：密钥类型、免费计划、自托管合规要求，见 License key and activation。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

在 Electron 桌面应用中集成 CKEditor 5（ZIP 自托管方案）完整指南