CKEditor 5 编辑器基础与配置教程

CKEditor 5 编辑器基础与配置教程

ckeditor5 具有模块化架构、现代集成和协作编辑等功能的强大富文本编辑器框架 项目地址: https://gitcode.com/gh_mirrors/ck/ckeditor5

前言

CKEditor 5 是一个现代化的富文本编辑器框架，它提供了强大的内容编辑功能和灵活的定制能力。本文将带你深入了解 CKEditor 5 编辑器的基本使用方法、配置选项以及核心 API，帮助你快速上手这个强大的工具。

环境准备

在开始之前，我们需要搭建一个基本的开发环境。你可以使用以下命令快速创建一个最小化的 CKEditor 5 开发环境：

npx -y degit ckeditor/ckeditor5-tutorials-examples/crash-course crash-course
cd crash-course

npm install
npm run dev

执行完毕后，打开终端显示的 URL，你应该能看到页面上显示"Hello world!"文本，这表示环境已经准备就绪。

创建编辑器实例

CKEditor 5 提供了多种编辑器类型，其中最基础的是 ClassicEditor。让我们看看如何创建一个经典编辑器实例：

import { ClassicEditor } from 'ckeditor5';
import 'ckeditor5/ckeditor5.css';

const element = document.querySelector('#app');
const editor = await ClassicEditor.create(element, {
    licenseKey: 'GPL' // 或者使用你的许可证密钥
});

这段代码做了以下几件事：

1. 导入 ClassicEditor 和必要的样式
2. 获取页面上的 DOM 元素
3. 使用 create() 方法创建编辑器实例

create() 方法是 CKEditor 5 的核心 API，它会：

• 将传入的 DOM 元素替换为编辑器 UI
• 使用该元素的 HTML 内容作为编辑器的初始内容

编辑器配置

你可能注意到初始创建的编辑器无法输入内容，这是因为 CKEditor 5 采用模块化设计，核心功能都通过插件实现。让我们添加两个基础插件：

import { ClassicEditor, Essentials, Paragraph } from 'ckeditor5';

const editor = await ClassicEditor.create(element, {
    licenseKey: 'GPL',
    plugins: [
        Essentials,
        Paragraph
    ]
});

插件系统解析

• Essentials：提供撤销(Undo)和重做(Redo)等基础功能
• Paragraph：支持段落格式和基本文本编辑

CKEditor 5 的插件系统是其灵活性的核心，每个功能（如加粗、斜体、表格等）都是独立的插件，可以按需加载。

工具栏配置

让我们为编辑器添加工具栏：

const editor = await ClassicEditor.create(element, {
    licenseKey: 'GPL',
    plugins: [
        Essentials,
        Paragraph
    ],
    toolbar: {
        items: [
            'undo',
            'redo'
        ]
    }
});

工具栏配置非常直观，只需在 items 数组中列出需要的功能按钮即可。CKEditor 5 会自动处理按钮的显示和交互逻辑。

编辑器核心 API

CKEditor 5 提供了丰富的 API 来操作编辑器内容。让我们深入了解几个最常用的方法：

1. 获取和设置内容

getData() 方法获取编辑器内容的 HTML 表示：

editor.getData(); // 返回类似 "<p>Hello world!</p>" 的字符串

setData() 方法用于设置编辑器内容：

editor.setData('<p>新内容</p>');

2. 执行命令

CKEditor 5 通过命令系统实现各种功能。例如执行撤销操作：

editor.execute('undo');

执行重做操作：

editor.execute('redo');

3. 销毁编辑器

当不再需要编辑器时，应该调用 destroy() 方法清理资源：

editor.destroy(); // 返回 Promise

注意：destroy() 是异步操作，如果需要在其后执行其他操作，应该使用 await。

使用 CDN 的注意事项

如果你选择通过 CDN 使用 CKEditor 5，需要注意以下几点：

1. 引入 CSS 和 JS 文件：

<link rel="stylesheet" href="CDN_URL/ckeditor5.css" />
<script src="CDN_URL/ckeditor5.umd.js"></script>

2. 访问全局变量：

const { ClassicEditor, Essentials } = CKEDITOR;

3. 许可证密钥需要使用有效的商业许可证

最佳实践

1. 按需加载插件：只加载需要的插件以减少包体积
2. 错误处理：对异步操作添加适当的错误处理
3. 生命周期管理：在组件销毁时调用 destroy() 方法
4. 内容安全：对用户输入的内容进行适当的过滤和转义

下一步

掌握了编辑器的基础使用后，下一步可以深入了解 CKEditor 5 的插件系统，学习如何开发自定义插件来扩展编辑器功能。插件开发是 CKEditor 5 最强大的特性之一，允许你完全定制编辑器的行为和外观。

希望本教程能帮助你快速上手 CKEditor 5。通过灵活的配置和丰富的 API，你可以构建出满足各种需求的富文本编辑解决方案。

ckeditor5 具有模块化架构、现代集成和协作编辑等功能的强大富文本编辑器框架 项目地址: https://gitcode.com/gh_mirrors/ck/ckeditor5