Spring Boot 集成 CKEditor 5 富文本编辑器:基于 CDN 的完整接入指南
Spring Boot 集成 CKEditor 5 富文本编辑器:基于 CDN 的完整接入指南
CKEditor 5 是一个纯 JavaScript/TypeScript 实现的开源富文本编辑框架,因此它可以运行在任何能够托管静态资源的后端环境之中,包括基于 Java 的 Spring Boot。本文将以官方 CDN(内容分发网络)方式为主线,一步步带你完成从创建 Spring Boot 工程、引入 CDN 资源、编写 Thymeleaf 模板与控制器,到最终把编辑器数据提交回后端的全流程;读完你将掌握一套不依赖 npm 打包工具、仅用几行 HTML 标签即可交付使用的接入方案。
为什么在 Spring Boot 中推荐使用 CDN 方式接入
CKEditor 5 官方并不提供专门针对 Spring Boot 的集成包,但这并不构成障碍:编辑器本身是纯前端库,服务端只需要做一件事——把包含编辑器脚本和容器的 HTML 页面正常返回给浏览器即可。
与 npm/源码打包方式相比,CDN 方式有三个突出的实践优势:
- 零构建工具:不需要 Webpack、Vite 或 Rollup,一个 HTML 模板加一个控制器即可运行;
- 版本可控:在
<script>与<link>标签中直接指定版本号,升级编辑器就是改一个数字; - 开源与商用功能分离:开源插件与 Premium 商业插件分别走不同的 CDN 文件,按需加载,按需付费。
CDN 方式的完整通用接入流程在 docs/getting-started/integrations-cdn/quick-start.md 中有更详细的介绍,本文则聚焦于它落地到 Spring Boot + Thymeleaf 工程里的具体做法。
第一步:准备 Spring Boot 工程
本指南假设你已经拥有了一个 Spring Boot 项目。若还没有,可以使用 Spring Initializr(start.spring.io)在线生成,具体工程骨架的搭建方式请查阅 Spring Boot 官方入门文档。
示例工程在 Spring Initializr 中选择了 Spring Web 与 Thymeleaf 两个起步依赖,最终 pom.xml 中的依赖清单如下:
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-thymeleaf</artifactId>
</dependency>
</dependencies>
注意:使用 CKEditor 5 的 Cloud CDN 服务需要先注册一个免费账户以获取许可证密钥(License Key),详见 docs/getting-started/licensing 下的许可证激活说明。
创建完成后,工程目录结构应类似于:
├── src
│ ├── main
│ │ ├── java
│ │ │ └── com
│ │ │ └── example
│ │ │ └── demo
│ │ │ └── DemoApplication.java
│ │ └── resources
│ │ ├── static
│ │ │ └── ...
│ │ ├── templates
│ │ │ ├── index.html
│ │ │ └── ...
│ │ └── application.properties
│ └── test
├── pom.xml
└── ...
关键点在于:视图模板必须放在 src/main/resources/templates 目录下(Thymeleaf 的默认视图解析路径),这样 @Controller 返回的视图名才能被正确解析。
第二步:在模板中引入 CKEditor 5 的资源与容器
在 src/main/resources/templates 目录下创建或修改 index.html,把编辑器的样式、脚本与挂载容器一并放入。开源与 Premium(商用)功能分别存放在不同的 CDN 文件中,因此资源标签也分为两组——只有当你确实使用 Premium 插件时才需要添加第二组标签:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>CKEditor 5 - Spring Boot CDN Integration</title>
<link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5/{版本号}/ckeditor5.css" />
<script src="https://cdn.ckeditor.com/ckeditor5/{版本号}/ckeditor5.umd.js"></script>
<!-- 仅在使用 Premium 功能时添加以下两个标签。 -->
<link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5-premium-features/{版本号}/ckeditor5-premium-features.css" />
<script src="https://cdn.ckeditor.com/ckeditor5-premium-features/{版本号}/ckeditor5-premium-features.umd.js"></script>
<!-- -->
<style>
.main-container {
width: 795px;
margin-left: auto;
margin-right: auto;
}
</style>
</head>
<body>
<div class="main-container">
<div id="editor">
<p>Hello from CKEditor 5!</p>
</div>
</div>
</body>
</html>
对这段模板的解读:
ckeditor5.css:编辑器 UI 与内容的全部样式;ckeditor5.umd.js是开源功能的 UMD 构建产物,加载后会向全局暴露CKEDITOR对象;<div id="editor">:编辑器的挂载容器。容器内已有的<p>Hello from CKEditor 5!</p>会被作为编辑器的初始内容加载——从源码看,ClassicEditor.create()会读取attachTo指定元素的现有内容作为根节点的初始数据,见 classiceditor.ts 中的normalizeRootsConfig()逻辑(该逻辑在 normalizerootsconfig.ts 中实现,负责把config.root.initialData、config.placeholder等归一化);- 版本号请替换为实际使用的版本(官方示例中使用的是
43.0.0),也可以借助模板引擎把它做成配置项统一维护。
第三步:编写编辑器初始化脚本
上面引入的两个脚本会分别暴露名为 CKEDITOR 与 CKEDITOR_PREMIUM_FEATURES 的全局变量。利用 JavaScript 的对象解构语法,可以从开源全局变量中取出编辑器类与所需插件,从 Premium 全局变量中取出商用插件,然后整体传入 create() 方法完成初始化:
<script>
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( /* ... */ );
</script>
配置项逐条解析
attachTo:指定编辑器要替换/挂载的 DOM 元素,这里用document.querySelector( '#editor' )找到模板中的容器。从 classiceditor.ts 的构造函数与create()实现(约 L328-L347)可以看到,create()返回 Promise,内部依次执行initPlugins()、ui.init()、data.init(),最后触发ready事件,这就是then/catch回调的由来;licenseKey:许可证密钥。使用 Cloud CDN 时必须填入合法密钥(GPL 场景可填'GPL'),否则编辑器会拒绝启动;plugins:插件数组,决定编辑器具备哪些能力。示例中的Essentials是一个聚合插件,从 essentials.ts 源码(L40-L41)可以看到它内部依赖了AccessibilityHelp、Clipboard、Enter、SelectAll、ShiftEnter、Typing、Undo七个基础插件;而Font同样是一个聚合插件,从 font.ts 的requires声明可知它聚合了FontFamily、FontSize、FontColor、FontBackgroundColor四个子特性。这也解释了为什么只需引入Font一个插件,工具栏上却能出现字体大小、字体族、字体颜色、背景色四个按钮;toolbar:工具栏按钮清单,其中的'|'是分隔符。按钮名与插件一一对应:undo/redo由 Essentials 依赖的Undo提供,bold/italic由Bold/Italic插件提供,fontSize/fontFamily/fontColor/fontBackgroundColor来自Font插件族,formatPainter则来自 Premium 的FormatPainter插件。
把脚本放回模板
初始化脚本必须放在 <div id="editor"> 容器之后,这样 DOM 元素已就绪、编辑器才能成功挂载。完整的最终模板如下:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>CKEditor 5 - Spring Boot CDN Integration</title>
<link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5/43.0.0/ckeditor5.css" />
<script src="https://cdn.ckeditor.com/ckeditor5/43.0.0/ckeditor5.umd.js"></script>
<!-- Add if you use premium features. -->
<link rel="stylesheet" href="https://cdn.ckeditor.com/ckeditor5-premium-features/43.0.0/ckeditor5-premium-features.css" />
<script src="https://cdn.ckeditor.com/ckeditor5-premium-features/43.0.0/ckeditor5-premium-features.umd.js"></script>
<!-- -->
<style>
.main-container {
width: 795px;
margin-left: auto;
margin-right: auto;
}
</style>
</head>
<body>
<div class="main-container">
<div id="editor">
<p>Hello from CKEditor 5!</p>
</div>
</div>
<script>
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( editor => {
window.editor = editor;
} )
.catch( error => {
console.error( error );
} );
</script>
</body>
</html>
第四步:创建控制器并把页面交给 Spring Boot 渲染
要让 Spring Boot 把这个 HTML 页面正常返回给浏览器,还需要在工程主包(com.example.demo)下创建一个 HomeController.java:
package com.example.demo;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.GetMapping;
@Controller
public class HomeController {
@GetMapping("/")
public String home() {
return "index";
}
}
这里的逻辑很简单:@GetMapping("/") 把根路径映射到 home() 方法,方法返回视图名 "index",Thymeleaf 模板引擎随后到 src/main/resources/templates/index.html 找到对应模板并渲染。
最后,启动应用:
- Linux/macOS:
./mvnw spring-boot:run - Windows:
mvnw.cmd spring-boot:run
然后在浏览器中访问 http://localhost:8080,即可看到带工具栏的经典(Classic)编辑器已经出现在页面上。
第五步:把编辑器内容提交回 Spring Boot 后端
页面能渲染出编辑器只是第一步,实际业务中通常还需要把编辑后的 HTML 内容保存到服务端。CKEditor 5 提供了多种数据获取方式,详见 docs/getting-started/setup/getting-and-setting-data.md,这里给出两种与 Spring Boot 配合的典型做法。
方式一:使用 <textarea> 的表单自动集成(Classic 编辑器)
这是最经典的方式,尤其适合内容管理系统、论坛、评论等场景。仅当 Classic 编辑器替换的是一个 <textarea> 元素时,表单提交时编辑器会自动把内容写回该 <textarea>,无需任何额外 JavaScript:
<form action="/save" method="post">
<textarea name="content" id="editor">
<p>This is some sample content.</p>
</textarea>
<p><input type="submit" value="Submit"></p>
</form>
这一行为并非巧合,而是由源码显式实现的:ClassicEditor 构造函数中调用了 attachToForm( this )(见 classiceditor.ts),而 attachtoform.ts 中的 attachToForm() 会检测源元素是否为位于 <form> 内的 <textarea>,若是则替换表单的 submit 逻辑,在每次提交前先执行 editor.updateSourceElement() 把最新内容同步回 <textarea>,并在编辑器销毁时清理监听器、还原原始 submit 方法。
注意:把数据库中的内容回填到
<textarea>时,需要对 HTML 做实体编码(例如把<p>Hello</p>输出为<p>Hello</p>),否则浏览器会把标签当成真实 DOM 解析。编码后简单内容虽无碍,但可避免丢失<或<IMPORTANT>之类的文本。当源元素不是<textarea>时,编辑器销毁后会清空其内容;若希望销毁时把数据管道输出写回源元素,可开启配置项updateSourceElementOnDestroy: true(该选项涉及安全考量,启用前需谨慎评估所用插件)。
在服务端,控制器可直接以表单字段接收 content 参数:
@PostMapping("/save")
@ResponseBody
public String save(@RequestParam("content") String content) {
// 此处将 content 持久化到数据库或其他存储。
return "saved";
}
方式二:通过 getData() 以 JavaScript 获取内容并异步提交
如果需要在任意时刻主动读取编辑器数据(例如点击自定义按钮后通过 Fetch/XHR 发送),可以使用 editor.getData()。关键在于:编辑器实例没有全局引用,需要把 then() 回调中的实例保存到外部变量:
let editor;
ClassicEditor
.create( {
attachTo: document.querySelector( '#editor' ),
licenseKey: '<YOUR_LICENSE_KEY>',
plugins: [ Essentials, Bold, Italic, Font, Paragraph ],
toolbar: [ 'undo', 'redo', '|', 'bold', 'italic' ]
} )
.then( newEditor => {
editor = newEditor;
} )
.catch( error => {
console.error( error );
} );
document.querySelector( '#saveBtn' ).addEventListener( 'click', () => {
const editorData = editor.getData();
fetch( '/api/editor/save', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify( { content: editorData } )
} );
} );
对应地,Spring Boot 控制器用 @RequestBody 接收 JSON:
@PostMapping("/api/editor/save")
@ResponseBody
public String save(@RequestBody Map<String, String> payload) {
String content = payload.get("content");
// 此处将 content 持久化到数据库或其他存储。
return "saved";
}
如果需要替换编辑器内容,则调用 editor.setData( '<p>Some text.</p>' )。当使用 getData() 同步获取内容时,建议配合 Autosave 自动保存特性或监听 window#beforeunload 事件,防止用户未保存就离开页面而丢失数据。
进阶:在 Spring Boot 中配合 Import Maps 使用 ESM 写法
如果团队希望以标准的 ESM 模块导入方式(import { ClassicEditor } from 'ckeditor5')替代全局变量解构,可以在页面中使用浏览器的 Import Maps 特性,把 ckeditor5 与 ckeditor5-premium-features 两个说明符映射到 CDN 地址,具体做法可参考 docs/getting-started/integrations-cdn/quick-start.md 中的"Advanced setup with import maps"一节。需要注意的是,Import Maps 属于浏览器原生模块特性,必须在本地服务器(如 Spring Boot 提供的 HTTP 服务)上运行页面,直接以 file:// 方式打开 HTML 会因 CORS 策略而失败——而 Spring Boot 恰好就是一个现成的 HTTP 服务,这正好契合本场景。
常见问题排查
| 现象 | 可能原因与排查方向 |
|---|---|
| 页面加载后没有编辑器 | 确认 index.html 位于 src/main/resources/templates 下;确认脚本放在容器 <div> 之后;打开浏览器控制台查看是否有 JS 报错 |
| 编辑器报许可证相关错误 | 使用 Cloud CDN 需要有效许可证密钥,检查 licenseKey 配置是否正确 |
| 表单提交后拿到的内容是旧数据 | 检查是否使用了 <textarea> 元素并位于 <form> 内;若在 onsubmit 中程序化读取 <textarea>,请先调用 editor.updateSourceElement() |
| 工具栏按钮缺失 | 按钮对应的插件未加入 plugins 数组,或插件与工具栏按钮名不匹配 |
下一步深入学习
- 数据读取与写入的完整 API 讲解:docs/getting-started/setup/getting-and-setting-data.md;
- 编辑器功能的细粒度配置方式(插件注册、工具栏定制、各功能配置项):docs/getting-started/setup/configuration.md;
- 单个功能的详细能力说明:docs/features/index.md;
- 想了解开源包整体导出了哪些模块与插件,可查看聚合入口 packages/ckeditor5/src/index.ts。