1. CKEditor 基础配置入门
作为一个在多个项目中集成过CKEditor的开发者，我深知初次接触这个富文本编辑器时的困惑。CKEditor 5是目前最流行的富文本编辑器之一，相比旧版本有了全新的架构设计。让我们从最基础的配置开始。
首先需要通过npm安装CKEditor：
bash复制npm install @ckeditor/ckeditor5-vue @ckeditor/ckeditor5-build-classic
然后在Vue组件中引入并使用：
javascript复制import ClassicEditor from '@ckeditor/ckeditor5-build-classic'
export default {
data() {
return {
editor: ClassicEditor,
editorData: '<p>初始内容</p>',
editorConfig: {
// 基础配置将在这里添加
}
}
}
}
在模板中使用：
html复制<ckeditor :editor="editor" v-model="editorData" :config="editorConfig"></ckeditor>
1.1 核心配置项解析
最基本的配置包括工具栏设置、语言配置和插件管理：
javascript复制editorConfig: {
language: 'zh-cn', // 设置中文界面
toolbar: {
items: [
'heading', '|',
'bold', 'italic', 'link', 'bulletedList', 'numberedList', '|',
'undo', 'redo'
]
}
}
这里的|符号用于在工具栏中创建视觉分隔线。我建议初次配置时保持工具栏简洁，只包含最常用的功能，等熟悉后再逐步扩展。
注意：CKEditor 5与4.x版本配置方式完全不同，5.x采用模块化设计，每个功能都是独立插件。
2. 深度定制工具栏功能
2.1 工具栏分组与排序
经过多个项目实践，我发现合理的工具栏分组能显著提升用户体验。下面是一个优化后的配置示例：
javascript复制toolbar: {
items: [
'heading', '|',
'fontFamily', 'fontSize', 'fontColor', 'fontBackgroundColor', '|',
'bold', 'italic', 'underline', 'strikethrough', 'subscript', 'superscript', '|',
'link', 'blockQuote', 'codeBlock', '|',
'alignment', 'indent', 'outdent', '|',
'bulletedList', 'numberedList', 'todoList', '|',
'imageUpload', 'mediaEmbed', 'insertTable', '|',
'undo', 'redo'
]
}
这种分组方式将相似功能放在一起：
- 第一组：文本样式
- 第二组：字体设置
- 第三组：基础格式
- 第四组：引用和代码
- 第五组：对齐和缩进
- 第六组：列表
- 第七组：媒体插入
- 最后是操作历史
2.2 自定义标题样式
CKEditor默认只支持h1-h3，但我们可以扩展：
javascript复制heading: {
options: [
{ model: 'paragraph', title: '正文', class: 'ck-heading_paragraph' },
{
model: 'heading1',
view: 'h1',
title: '标题1',
class: 'ck-heading_heading1'
},
// 添加h4-h6
{
model: 'heading4',
view: 'h4',
title: '小标题',
class: 'ck-heading_heading4'
}
]
}
在实际项目中，我通常会根据设计稿添加一些自定义样式类：
javascript复制{
model: 'redTitle',
view: {
name: 'h3',
classes: 'text-red-500'
},
title: '红色标题',
class: 'ck-heading_red'
}
3. 中文环境与图片上传配置
3.1 完整的中文语言支持
虽然设置language: 'zh-cn'能实现基本汉化，但完整的中文支持需要：
- 引入中文语言包：
javascript复制import '@ckeditor/ckeditor5-build-classic/build/translations/zh-cn.js'
- 确保所有插件都有中文翻译。我曾遇到表格插件没有完全汉化的问题，解决方案是：
javascript复制import Table from '@ckeditor/ckeditor5-table/src/table'
import TableToolbar from '@ckeditor/ckeditor5-table/src/tabletoolbar'
// 自定义中文翻译
ClassicEditor.builtinPlugins.forEach(plugin => {
if (plugin.pluginName === 'Table') {
plugin.init = function() {
this.editor.locale.t('Table properties') = '表格属性'
// 其他翻译项...
}
}
})
3.2 图片上传功能实现
图片上传是实际项目中最常需要的功能之一。完整实现需要：
- 创建上传适配器：
javascript复制class MyUploadAdapter {
constructor(loader) {
this.loader = loader
}
upload() {
return this.loader.file.then(file => {
return new Promise((resolve, reject) => {
const formData = new FormData()
formData.append('file', file)
axios.post('/api/upload', formData, {
headers: {
'Content-Type': 'multipart/form-data'
},
onUploadProgress: progressEvent => {
if (progressEvent.lengthComputable) {
this.loader.uploadTotal = progressEvent.total
this.loader.uploaded = progressEvent.loaded
}
}
}).then(response => {
resolve({
default: response.data.url
})
}).catch(error => {
reject(`上传失败: ${error.message}`)
})
})
})
}
}
- 注册适配器插件：
javascript复制function MyUploadAdapterPlugin(editor) {
editor.plugins.get('FileRepository').createUploadAdapter = (loader) => {
return new MyUploadAdapter(loader)
}
}
- 添加到编辑器配置：
javascript复制editorConfig: {
extraPlugins: [MyUploadAdapterPlugin],
// 其他配置...
}
4. 高级功能与性能优化
4.1 自定义插件开发
当内置功能不满足需求时，可以开发自定义插件。例如添加一个"插入特殊符号"的插件：
- 创建插件类：
javascript复制import Plugin from '@ckeditor/ckeditor5-core/src/plugin'
import ButtonView from '@ckeditor/ckeditor5-ui/src/button/buttonview'
export default class SpecialCharacters extends Plugin {
init() {
const editor = this.editor
editor.ui.componentFactory.add('specialCharacters', locale => {
const view = new ButtonView(locale)
view.set({
label: '特殊符号',
tooltip: true,
withText: true
})
view.on('execute', () => {
// 打开符号选择弹窗
this._showPicker(editor)
})
return view
})
}
_showPicker(editor) {
// 实现符号选择逻辑
}
}
- 注册并使用插件：
javascript复制import SpecialCharacters from './SpecialCharacters'
editorConfig: {
plugins: [SpecialCharacters, /* 其他插件 */],
toolbar: {
items: ['specialCharacters', /* 其他工具 */]
}
}
4.2 性能优化技巧
在大文档编辑场景下，CKEditor可能会变慢。以下是我总结的优化方案：
- 延迟加载：只在需要时加载编辑器
javascript复制const Editor = () => import('@ckeditor/ckeditor5-vue')
- 精简构建：只包含必要的插件
javascript复制import Essentials from '@ckeditor/ckeditor5-essentials/src/essentials'
import Bold from '@ckeditor/ckeditor5-basic-styles/src/bold'
// 只引入需要的插件...
ClassicEditor.create(document.querySelector('#editor'), {
plugins: [Essentials, Bold, Italic /*...*/],
toolbar: ['bold', 'italic' /*...*/]
})
- 配置缓存：启用自动保存和恢复
javascript复制autosave: {
save(editor) {
localStorage.setItem('ckeditor-autosave', editor.getData())
},
waitingTime: 5000 // 5秒后自动保存
}
- 限制历史记录：减少内存占用
javascript复制history: {
maxItems: 50 // 只保留最近的50个操作
}
在实际项目中，我会根据内容复杂度动态调整这些参数。例如，对于简单的评论框使用轻量配置，而对完整的文章编辑器则启用更多功能。