Spring Boot 集成 CKEditor 5 富文本编辑器:基于 CDN 的完整接入指南

原创2026-09-15 13:06:361,674 阅读
文章标签:前端富文本UI组件

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">
		&lt;p&gt;This is some sample content.&lt;/p&gt;
	</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> 输出为 &lt;p&gt;Hello&lt;/p&gt;),否则浏览器会把标签当成真实 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 数组,或插件与工具栏按钮名不匹配

下一步深入学习

登录后查看全文
ckeditor5