Django-CKEditor-5 全功能工具栏配置完整指南_技术教程

本文详解如何在 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）为可选项，按需启用。