如何在 Django 中正确使用 CKEditor 并保存富文本内容

本文详解 django 中 ckeditor 表单提交失败、显示为原始 textarea 的根本原因——未调用 `form.is_valid()` 与 `cleaned_data`，并提供完整修复方案，确保富文本内容被正确解析并存入数据库。

在 Django 项目中集成 CKEditor（如 django-ckeditor）时，一个常见误区是：表单渲染正常、编辑器界面可用，但提交后数据库中却存入了包含 <textarea> 标签的 HTML 片段，而非纯净的富文本内容。正如问题中所示，{{ form.as_p }} 渲染出的并非纯文本输入框，而是嵌套了 CKEditor 初始化逻辑的 <div><textarea> 结构；而直接将 form 实例（而非其清洗后的值）赋给模型字段，会导致 Django 将整个未处理的表单对象（含 HTML 模板结构）错误地序列化存储。

根本原因在于：
✅ CKEditorWidget 是前端增强组件，它通过 JavaScript 将 <textarea> 升级为可视化编辑器，但提交时仍以普通 POST 字段（name="body"）发送纯 HTML 字符串；
❌ 原始代码中 f = Document(..., body = form, ...) 错误地将整个 PostForm 实例传入 body 字段，而 RichTextField 期望的是字符串（如 "<p>Hello</p>"），不是 Form 对象；
❌ 未调用 form.is_valid()，导致 form.cleaned_data 不可用，无法安全提取已清洗、转义、验证过的富文本内容。

✅ 正确做法：始终通过 cleaned_data 获取富文本值

首先，修正 forms.py 中的表单定义（注意：forms.Form 无需 Meta.model，且 fields 属性仅适用于 ModelForm）：

# forms.py
from django import forms
from ckeditor.widgets import CKEditorWidget

class PostForm(forms.Form):
    body = forms.CharField(widget=CKEditorWidget())
    # 注意：此处无需 Meta 类 —— 这是普通 Form，非 ModelForm

接着，在视图中严格遵循 Django 表单处理规范：

# views.py
from django.shortcuts import render, HttpResponseRedirect
from django.urls import reverse
from .forms import PostForm
from .models import Document, Category

def add_document(request):
    if request.method == "POST":
        form = PostForm(request.POST)  # 绑定 POST 数据
        if form.is_valid():  # ✅ 关键：触发验证与清洗
            body = form.cleaned_data['body']  # ✅ 获取清洗后的 HTML 字符串
            header = request.POST.get("header", "")
            category_id = request.POST.get("category")

            try:
                category = Category.objects.get(id=category_id)
                doc = Document.objects.create(
                    header=header,
                    body=body,  # ✅ 直接传入 clean HTML 字符串
                    category=category
                )
                return HttpResponseRedirect(
                    reverse("core:category", kwargs={"id": category_id})
                )
            except Category.DoesNotExist:
                form.add_error('category', 'Invalid category selected.')
        # 若验证失败，继续渲染表单（带错误提示）
    else:
        form = PostForm()  # GET 请求：返回空表单

    categories = Category.objects.all()
    languages = get_language_choices()
    context = {
        "allCategories": categories,
        "form": form,  # ✅ 传递实例，非类
        "languages": languages
    }
    return render(request, "documents/add-document.html", context)

⚠️ 同时检查模板与静态资源

确保 add-document.html 正确加载 CKEditor 资源：

Magic AI Avatars

神奇的AI头像，获得200多个由AI制作的自定义头像。

下载

<!-- documents/add-document.html -->
<form method="post">
    {% csrf_token %}
    <div class="form-group">
        {{ form.as_p }}
        {{ form.media }}  <!-- ✅ 必须存在：注入 CKEditor JS/CSS -->
    </div>
    <button type="submit">Save Document</button>
</form>

? {{ form.media }} 是关键！它由 CKEditorWidget 自动生成，负责引入 ckeditor.js、配置脚本及皮肤资源。缺失此行将导致编辑器不初始化，退化为普通 textarea。

? 额外建议：升级为 ModelForm（推荐）

为减少重复代码、自动绑定字段与验证，建议改用 ModelForm：

# forms.py
class PostForm(forms.ModelForm):
    class Meta:
        model = Document
        fields = ['header', 'body', 'category']
        widgets = {
            'body': CKEditorWidget(config_name='default'),  # 可选自定义配置
        }

对应视图简化为：

def add_document(request):
    if request.method == "POST":
        form = PostForm(request.POST)
        if form.is_valid():
            doc = form.save()  # ✅ 自动处理所有字段，包括 RichTextField
            return HttpResponseRedirect(
                reverse("core:category", kwargs={"id": doc.category_id})
            )
    else:
        form = PostForm()
    # ... 渲染逻辑同上

✅ 总结

遵循以上规范，CKEditor 即可无缝融入 Django 表单流程，实现所见即所得的富文本编辑与可靠持久化。