在 Vanilla JS 项目中安装 CKEditor 5：npm 与 ZIP 完整快速上手指南

在 Vanilla JS 项目中安装 CKEditor 5npm 与 ZIP 完整快速上手指南【免费下载链接】ckeditor5Powerful rich text editor framework with a modular architecture, modern integrations, and features like collaborative editing.项目地址: https://gitcode.com/GitHub_Trending/ck/ckeditor5本指南面向不使用前端框架、以原生 JavaScriptVanilla JS构建 Web 应用的前端开发者介绍在当前 CKEditor 5 开源仓库包版本 48.5.0中通过npm或ZIP 压缩包两种方式安装并运行 CKEditor 5 的完整流程。读完本文你将掌握包安装、模块与 CSS 导入、编辑器创建与配置、以及商业版 premium features 的集成方法能够在浏览器中快速跑起一个可用的富文本编辑器。为什么需要两种安装方式CKEditor 5 是一个模块化架构的富文本编辑器框架。不同于下载一个 JS 文件就完事的传统编辑器它的源码按包package拆分并基于 ES Modules 组织因此安装方式会直接影响你后续的构建与部署策略npm 方式适合已经或愿意引入 JavaScript 打包器的现代前端工程可以按需引入插件构建产物更小ZIP 方式适合不想引入打包器、也不依赖 CDN 的部署场景直接使用官方预构建好的完整 bundle。两种方式在44.0.0 版本之后都要求配置licenseKey属性才能运行编辑器详见下文许可证要求。方式一通过 npm 安装前置条件需要一个打包器使用 npm 安装时**必须借助打包器bundler**来正确构建 JavaScript 文件。CKEditor 5 兼容目前所有主流现代 JavaScript 打包器如需快速搭建一个全新项目官方推荐使用 Vite在其脚手架指南中可以找到npm create vite一类的初始化命令。安装主包执行下面的命令安装包含全部开源插件的 CKEditor 5 主包npm install ckeditor5在当前仓库中该包对应 packages/ckeditor5/package.json。从其中可以确认两点关键事实该包是一个type: module的 ES Module 包其入口为src/index.ts发布产物为dist/ckeditor5.js它的 dependencies 以workspace:*的方式聚合了仓库内几乎全部官方开源包从编辑引擎、六大编辑器类型到字体、表格、图片、列表、代码块等特性插件。更具体地说packages/ckeditor5/src/index.ts 只是把所有这些官方包统一export *出来。所以import { ClassicEditor, ... } from ckeditor5时你拿到的其实是跨包的聚合出口——这也是为什么一个包搞定所有开源插件。导入模块与样式安装完成后即可从ckeditor5包导入所有模块。同时CSS 样式必须单独导入JS 与样式分离便于打包器处理树摇与按需加载import { ClassicEditor, Essentials, Bold, Italic, Font, Paragraph } from ckeditor5; import ckeditor5/ckeditor5.css;提示非英语界面导入并注册 UI 翻译仅对美式英语是可选的。如需其他语言界面请参考 UI 语言设置指南中介绍的翻译导入方式。许可证要求从版本 44.0.0 起licenseKey属性是使用编辑器的必要条件。如果你通过 npm 使用自托管self-hosted编辑器要么必须遵守 GPL 协议在配置中填GPL要么购买自托管分发许可证。也可以注册免费试用计划来测试编辑器、评估自托管方案。关于GPL键许可证与激活指南还补充了一个重要限制GPL键只适用于自托管分发npm 或 ZIP云托管 CDN 分发不接受该键云分发始终要求商业许可证键。此外该指南详细区分了 trial14 天试用、development开发不消耗 editor loads但限制本地域名、production生产按用量计费时消耗 loads与 evaluation 四种许可证键类型需要正式商用前务必先阅读。创建一个最小可运行编辑器创建编辑器的核心模式是选择编辑器类型 → 配置插件与工具栏 → 调用create()。以最常用的经典编辑器ClassicEditor为例ClassicEditor .create( { attachTo: document.querySelector( #editor ), licenseKey: YOUR_LICENSE_KEY, // 或 GPL。 plugins: [ Essentials, Bold, Italic, Font, Paragraph ], toolbar: [ undo, redo, |, bold, italic, |, fontSize, fontFamily, fontColor, fontBackgroundColor ], root: { placeholder: Type here... } } ) .then( /* ... */ ) .catch( /* ... */ );配合如下 HTML 挂载点create()返回 Promise初始化成功后可在then回调中拿到editor实例失败时进入catchdiv ideditor pHello from CKEditor 5!/p /div这就是让一个骨架级编辑器在浏览器中运行所需的全部代码。对上述配置稍作拆解attachTo指向编辑器挂载的 DOM 元素。注意不同编辑器类型的挂载配置不同——Inline、Balloon、Decoupled 等多使用root.element而 MultiRoot 编辑器需要roots对象同时声明多个根详见 编辑器类型指南。原文档特别强调多根编辑器multi-root editor需要更高级的 roots 配置。plugins传入已导入的插件类。其中Essentials是一个必备功能合集。从源码 packages/ckeditor5-essentials/src/essentials.ts 可以看到它聚合了AccessibilityHelp、Clipboard、Enter、SelectAll、ShiftEnter、Typing、Undo七个插件使编辑器具备与textarea类似的基础编辑能力但它不定义任何块级容器例如段落Paragraph因此文档明确提示如果编辑器需要处理块级内容务必额外引入Paragraph——这正是上面示例同时引入Paragraph的原因。toolbar按字符串 ID 列出工具栏按钮|用于插入分隔符。可用的按钮 ID 由已注册插件决定例如bold/italic来自Bold/ItalicfontSize等来自Font。更全面的配置方法见 配置指南 与 工具栏指南。root.placeholder设置编辑区占位提示文本与之同族的root.initialData可用来以编程方式指定初始内容详见下文下一步。方式二通过 ZIP 压缩包安装如果你不想用 npm 构建项目也无法依赖 CDN 交付可以下载包含 CKEditor 5 及其全部插件的现成文件。下载与解压从官方 CDN 的ckeditor5-{版本号}/zip/路径下载最新 CKEditor 5 分发的 ZIP 压缩包当前仓库对应版本为 48.5.0下载地址中的版本号应与你实际使用的版本一致将压缩包解压到项目内的专用目录例如vendor/建议在目录名中包含编辑器版本号这样每次升级新版本时可确保正确的缓存失效策略。ZIP 包内的文件清单解压后你会得到以下文件文件说明index.html一个已包含可用编辑器的示例页面ckeditor5/ckeditor5.js即用型编辑器 ESM bundle内含编辑器与全部插件推荐构建ckeditor5/ckeditor.js.map上述 ESM bundle 的 source mapckeditor5/ckeditor5.umd.js即用型编辑器 UMD bundle内含编辑器与全部插件次要构建ckeditor5/ckeditor5.umd.js.map上述 UMD bundle 的 source mapckeditor5/*.css编辑器样式表大多数场景使用ckeditor5.css其他样式文件见 编辑器与内容样式指南translations/编辑器 UI 翻译文件见 UI 语言设置指南README.md、LICENSE.md说明与许可文件ZIP 方式同样受 44.0.0 起的licenseKey要求约束自托管场景下需遵守 GPL 或购买自托管分发许可证。运行示例页面查看编辑器实际效果最快捷的方式是用 HTTP 服务器来托管index.html。重要警告必须在本地服务器环境运行。ZIP 包默认通过 import maps 加载模块直接用浏览器打开本地 HTML 文件会触发浏览器的安全规则CORS 策略要求模块必须同源加载。因此请使用nginx、caddy、http-server等工具将文件以 HTTP/HTTPS 方式提供服务。安装商业版 premium features开源版之外CKEditor 5 还有一系列商业付费特性premium features如 Format Painter格式刷、协作编辑、导出 PDF/Word 等。它们与开源版一样支持 npm 与 ZIP 两种安装方式。通过 npm 安装 premium features所有 premium features 都打包在独立的ckeditor5-premium-features包中安装方式与开源包一致npm install ckeditor5-premium-features之后从两个包分别导入模块并分别导入各自的 CSSimport { ClassicEditor, Essentials, Bold, Italic, Paragraph, Font } from ckeditor5; import { FormatPainter } from ckeditor5-premium-features; import ckeditor5/ckeditor5.css; import ckeditor5-premium-features/ckeditor5-premium-features.css; ClassicEditor .create( { attachTo: document.querySelector( #editor ), licenseKey: YOUR_LICENSE_KEY, plugins: [ Essentials, Bold, Italic, Paragraph, Font, FormatPainter ], toolbar: [ undo, redo, |, bold, italic, |, fontSize, fontFamily, fontColor, fontBackgroundColor, |, formatPainter ], root: { placeholder: Type here... } } ) .then( /* ... */ ) .catch( /* ... */ );div ideditor pHello from CKEditor 5!/p /div要点与开源版一致把导入的插件传入create()配置、在toolbar中添加对应的工具栏项。但请注意使用 premium features 必须用合法的许可证键激活参见下文获取 premium features 许可证键。从 npm 自托管时同样需要购买 premium features 的许可证。通过 ZIP 安装 premium features从官方 CDN 的ckeditor5-premium-features-{版本号}/zip/路径下载包含 premium features 的最新分发压缩包解压到项目内专用目录同样建议目录名带上版本号以利于缓存失效。ZIP 包结构如下index.html—— 包含可用编辑器的示例页ckeditor5/目录ckeditor5.js—— 编辑器 ESM bundle推荐构建ckeditor.js.map—— 上述 bundle 的 source mapckeditor5.umd.js—— 编辑器 UMD bundle次要构建ckeditor5.umd.js.map—— 上述 UMD bundle 的 source map*.css—— 编辑器样式表多数场景用ckeditor5.css其他文件见 编辑器与内容样式指南translations/—— 编辑器 UI 翻译见 UI 语言设置指南ckeditor5-premium-features/子目录ckeditor5-premium-features.js—— premium features 的 ESM bundle推荐构建ckeditor5-premium-features.umd.js—— premium features 的 UMD bundle次要构建*.css—— premium features 样式表多数场景用ckeditor5-premium-features.csstranslations/—— premium features 的 UI 翻译README.md、LICENSE.md。与开源版 ZIP 一样最快捷的验证方式是把index.html通过 HTTP 服务器托管同样必须遵守 CORS 同源加载规则不能直接双击打开本地 HTML 文件。获取 premium features 许可证键激活 CKEditor 5 premium features 需要商业许可证。最简单的途径是注册 CKEditor Premium Features 的14 天免费试用无需绑定信用卡来测试全部付费特性也可以通过官方销售渠道获取定制方案。拿到激活密钥后按 许可证与激活指南 将其填入配置的licenseKey字段即可。下一步让编辑器真正可用安装完成、编辑器能渲染之后通常会继续做三件事读写编辑器数据用editor.getData()获取内容例如通过 JS 发送到服务器用editor.setData()替换内容或用root.initialData配置项以编程方式指定初始数据它会覆盖 HTML 层提供的内容。详细示例见 获取与设置数据指南。若编辑器挂载在textarea上Classic editor 在表单提交时会自动把内容同步回该元素无需额外 JS。进一步定制编辑器参考 配置指南 了解全部配置项如updateSourceElementOnDestroy、自动保存、PendingActions 等生命周期与行为控制。按需开启更多特性浏览 特性索引挑选图片、表格、列表、协作等能力加入plugins与toolbar。小结无论选择 npm 还是 ZIPCKEditor 5 的接入模式都统一为选编辑器类型 → 装配插件 → 配置工具栏 →create()。npm 路径适合已使用打包器的工程并支持按需引入ZIP 路径则面向免构建、免 CDN 的部署。自 44.0.0 起两者都必须提供licenseKeyGPL 开源使用填GPL商业使用申请对应许可证premium features 则另需独立的商业激活密钥。结合本仓库中 packages/ckeditor5/src/index.ts 的聚合导出与 packages/ckeditor5-essentials/src/essentials.ts 的插件组合你可以随时回到源码层面验证每个配置项的真实行为。【免费下载链接】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），仅供参考