本文详解如何在 django-ckeditor-5 中启用完整工具栏（如字体样式、表格、代码块、图片高级设置等），替代 ckeditor 4 的 `'toolbar': 'full'` 写法，提供可直接复用的 `ckeditor_5_configs` 配置及模型集成方法。
Django-CKEditor-5（基于 CKEditor 5 构建）与旧版 CKEditor 4 在配置方式上有根本性差异：它不再支持 'toolbar': 'full' 这类简写模式，而是要求显式声明所需工具栏项（buttons）、区块工具栏（blockToolbar）、插件配置（如 image、table、heading）及扩展选项（如字体颜色、表格样式）。以下为生产环境推荐的完整配置方案。
✅ 正确配置 CKEDITOR_5_CONFIGS
在 settings.py 中定义 CKEDITOR_5_CONFIGS 字典，建议至少配置一个名为 'extends' 的完整配置项（区别于精简的 'default'）：
# settings.py
# 可选：自定义调色板（用于表格/字体背景色）
customColorPalette = [
{'color': 'hsl(4, 90%, 58%)', 'label': 'Red'},
{'color': 'hsl(340, 82%, 52%)', 'label': 'Pink'},
{'color': 'hsl(291, 64%, 42%)', 'label': 'Purple'},
{'color': 'hsl(262, 52%, 47%)', 'label': 'Deep Purple'},
{'color': 'hsl(231, 48%, 48%)', 'label': 'Indigo'},
{'color': 'hsl(207, 90%, 54%)', 'label': 'Blue'},
]
CKEDITOR_5_CONFIGS = {
# 基础配置（仅含常用按钮）
'default': {
'toolbar': ['heading', '|', 'bold', 'italic', 'link', 'bulletedList', 'numberedList', 'blockQuote', 'imageUpload'],
},
# 【推荐】全功能配置 —— 替代 CKEditor 4 的 'full' 模式
'extends': {
'blockToolbar': [
'paragraph', 'heading1', 'heading2', 'heading3',
'|', 'bulletedList', 'numberedList', '|', 'blockQuote'
],
'toolbar': [
'heading', '|',
'outdent', 'indent', '|',
'bold', 'italic', 'underline', 'strikethrough', 'code',
'subscript', 'superscript', 'highlight', '|',
'codeBlock', 'sourceEditing', '|',
'insertImage', 'mediaEmbed', '|',
'bulletedList', 'numberedList', 'todoList', '|',
'blockQuote', 'insertTable', '|',
'fontSize', 'fontFamily', 'fontColor', 'fontBackgroundColor', '|',
'removeFormat', 'link',
],
# 图片上传与样式配置
'image': {
'toolbar': [
'imageTextAlternative', '|',
'imageStyle:alignLeft', 'imageStyle:alignRight',
'imageStyle:alignCenter', 'imageStyle:side'
],
'styles': ['full', 'side', 'alignLeft', 'alignRight', 'alignCenter']
},
# 表格增强功能（含边框/背景色自定义）
'table': {
'contentToolbar': [
'tableColumn', 'tableRow', 'mergeTableCells',
'tableProperties', 'tableCellProperties'
],
'tableProperties': {
'borderColors': customColorPalette,
'backgroundColors': customColorPalette
},
'tableCellProperties': {
'borderColors': customColorPalette,
'backgroundColors': customColorPalette
}
},
# 标题级别定义（支持 class 属性，便于 CSS 定制）
'heading': {
'options': [
{'model': 'paragraph', 'title': 'Paragraph', 'class': 'ck-heading_paragraph'},
{'model': 'heading1', 'view': 'h1', 'title': 'Heading 1', 'class': 'ck-heading_heading1'},
{'model': 'heading2', 'view': 'h2', 'title': 'Heading 2', 'class': 'ck-heading_heading2'},
{'model': 'heading3', 'view': 'h3', 'title': 'Heading 3', 'class': 'ck-heading_heading3'},
]
}
},
# 列表增强（支持编号起始值、倒序、样式）
'list': {
'properties': {
'styles': True,
'startIndex': True,
'reversed': True,
}
}
}✅ 在模型中使用完整配置
确保已安装 django-ckeditor-5 并完成基础配置（如 STATIC_URL、MEDIA_URL、MEDIA_ROOT）。然后在模型字段中指定 config_name='extends'：
# models.py
from django.db import models
from ckeditor_5.fields import CKEditor5Field
class Article(models.Model):
title = models.CharField(max_length=200)
# 使用完整工具栏配置
content = CKEditor5Field('Content', config_name='extends')
def __str__(self):
return self.title⚠️ 注意事项：CKEditor5Field 不再接受 config_name='default' 以外的字符串作为快捷别名；必须在 CKEDITOR_5_CONFIGS 中明确定义该键。所有工具栏项名称（如 'codeBlock', 'sourceEditing', 'todoList'）需与 CKEditor 5 官方插件名 严格一致，拼写错误将导致按钮不显示。若使用 sourceEditing（源码编辑），需确保后端允许 HTML 存储（默认已开启），并注意 XSS 防护（建议配合 bleach 库清洗输出）。自定义 CSS（通过 CKEDITOR_5_CUSTOM_CSS）或文件存储（CKEDITOR_5_FILE_STORAGE）为可选项，按需启用。
完成配置后，重启 Django 开发服务器，访问 Admin 或表单页面即可看到功能完备的 CKEditor 5 编辑器——真正实现“所见即所得”的专业富文本体验。
