Django-富文本

这篇讲什么

  • 富文本编辑器让后台输入带格式的 HTML,前台再原样渲染出来——代价是「允许 HTML 进数据库」,所以安全边界必须一起讲。
  • 这篇用 django-tinymce(本机实测 5.0.0)走三条路:在站点管理里直接用、在自己的表单和视图里用、以及显示富文本内容时怎么防 XSS。老笔记里那个 TinyMCE 3 时代的脚本路径已经不存在了,一并更正。

安装

1
pip install django-tinymce          # 本机实测版本 5.0.0
  • 它会把 TinyMCE 编辑器本体一起打进包里,所以不用再单独去官网下 JS,也不需要 CDN。
  • 老笔记写的是 pip install django-tinymce 之后引 /static/tiny_mce/tiny_mce.js —— 那是 TinyMCE 3 时代的路径,现在这个文件不存在(实测 static/tiny_mce/tiny_mce.js 找不到;实际存在的是 static/tinymce/tinymce.min.js 和 static/django_tinymce/init_tinymce.js)。

在站点管理中使用

  • 配置 settings.py

    settings.py
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    INSTALLED_APPS = [
    "django.contrib.admin",
    "django.contrib.auth",
    "django.contrib.contenttypes",
    "django.contrib.sessions",
    "django.contrib.messages",
    "django.contrib.staticfiles",
    "myapp.apps.MyappConfig",
    "tinymce",
    ]
    • 应用名按 PEP8 全小写(老笔记写的是 myApp)。写成 "myapp" 或 "myapp.apps.MyappConfig" 都可以,后者是 startapp 生成的写法。
  • 末尾加编辑器配置

    1
    2
    3
    4
    5
    6
    7
    8
    # 富文本:随包带的 TinyMCE 是 7.8.0(实测 majorVersion "7", minorVersion "8.0")
    TINYMCE_DEFAULT_CONFIG = {
    "height": 600,
    "width": 900,
    "menubar": "edit insert view format table tools",
    "plugins": "lists link image table code autoresize",
    "toolbar": "undo redo | bold italic | alignleft aligncenter alignright | bullist numlist | link image | code",
    }
    • 老笔记这段是 {'theme': 'advanced', 'width': 400, 'height': 800}。实测这个字典不会报错,内容会原样塞进 data-mce-conf 属性里,但 theme: 'advanced' 在 TinyMCE 4 之后就没有了,属于写了没人认的键(真正生效的是 height / width 这类 7.x 认识的选项)。
  • 定义模型

    myapp/models.py
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    from django.db import models
    from tinymce.models import HTMLField


    class Article(models.Model):
    title = models.CharField(max_length=100)
    content = HTMLField() # 底层就是 TextField,只是表单里换成编辑器

    def __str__(self):
    return self.title
    • 网上很多教程写 from tinymce.models import TinyMCEField,这个类不存在(实测 hasattr(tinymce.models, "TinyMCEField") 为 False),会 ImportError。它对外只导出 HTMLField。

    • 迁移照旧:

      1
      2
      python manage.py makemigrations
      python manage.py migrate
  • 注册到 admin

    myapp/admin.py
    1
    2
    3
    4
    5
    from django.contrib import admin

    from myapp.models import Article

    admin.site.register(Article)
  • 根路由里挂上它的 URL

    project/urls.py
    1
    2
    3
    4
    5
    6
    7
    from django.contrib import admin
    from django.urls import include, path

    urlpatterns = [
    path("admin/", admin.site.urls),
    path("tinymce/", include("tinymce.urls")),
    ]
    • 这一步主要是给图片/文件上传浏览用的。实测 tinymce.urls 里只有 3 条路由(flatpages_link_list、compressor、filebrowser),所以直接访问 /tinymce/ 会 404 —— 这是正常的,它不是一个页面入口。

    • 配完后实测 python manage.py check 与 migrate 都通过:

      1
      System check identified no issues (0 silenced).
    • 打开 admin 的新增页(实测 200),页面里会出现这两个脚本:

      1
      2
      /static/tinymce/tinymce.min.js
      /static/django_tinymce/init_tinymce.js
    • 在编辑器里输入「你好 世界」提交,库里存的是:

      1
      <p>你好 <strong>世界</strong></p>
      • 也就是说 HTMLField 存的是原始 HTML,不是纯文本。

在自己的表单/视图里用

  • 老笔记这一节是手写 <textarea> + tinyMCE.init({...}),整套作废(tiny_mce.js 这个文件在当前版本里不存在)。现代做法是让表单自己把 JS 带出来,一行都不用手写。

  • 表单

    myapp/forms.py
    1
    2
    3
    4
    5
    6
    7
    8
    9
    from django import forms

    from myapp.models import Article


    class ArticleForm(forms.ModelForm):
    class Meta:
    model = Article
    fields = ["title", "content"]
  • 视图

    myapp/views.py
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    from django.shortcuts import render

    from myapp.forms import ArticleForm


    def new_article(request):
    if request.method == "POST":
    form = ArticleForm(request.POST)
    if form.is_valid():
    form.save()
    return render(request, "myapp/new_article.html", {"form": ArticleForm(), "saved": True})
    else:
    form = ArticleForm()
    return render(request, "myapp/new_article.html", {"form": form})
  • 模板:关键是 {{ form.media }}

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    <!DOCTYPE html>
    <html lang="zh">
    <head>
    <meta charset="UTF-8">
    <title>富文本</title>
    {{ form.media }} {# 这一行会输出 tinymce.min.js 与 init_tinymce.js #}
    </head>
    <body>
    <form method="post" action="">
    {% csrf_token %}
    {{ form.title }}
    {{ form.content }}
    <input type="submit" value="提交">
    </form>
    </body>
    </html>
    • 实测 HTMLField 渲染出的控件长这样(class="... tinymce" 和 data-mce-conf 就是 init_tinymce.js 用来找到并初始化编辑器的依据):

      1
      2
      3
      4
      <textarea class="vLargeTextField tinymce" cols="40" rows="10"
      data-mce-conf="{&quot;selector&quot;: &quot;#id_content&quot;, ...}"
      id="id_content" name="content">
      </textarea>
    • {{ form.media }} 输出的两条 script(实测):

      1
      2
      <script src="/static/tinymce/tinymce.min.js"></script>
      <script src="/static/django_tinymce/init_tinymce.js"></script>
  • 静态文件必须可达

    • 上面两个 JS 是从 /static/ 出去的,所以要满足其一:DEBUG = True(开发时 Django 直接服务 app 的 static/),或者上线前 python manage.py collectstatic 把它们收进 STATIC_ROOT。
    • 页面能打开但编辑器不出来,第一件事就是打开控制台看这两个 JS 是不是 404。

显示富文本内容时的安全边界

  • 库里存的是 HTML,模板里默认会转义,所以直接 {{ article.content }} 会把标签当文字显示。要渲染成 HTML:

    1
    {{ article.content|safe }}
  • |safe 等于关掉这段的 XSS 防护。如果内容来自不可信用户,至少要:

    • 在保存时用表单/序列化器清洗(django.utils.html.escape 或第三方 bleach 类库做白名单),或者
    • 只允许固定标签(TinyMCE 侧用 valid_elements 之类配置限制),别把 |safe 当默认。
  • 反过来,HTMLField 本身不做任何清洗,它只是个带编辑器的 TextField(实测存进去什么就是什么)。

新手卡点清单

  • 都是实测过的:

    卡点 症状 正确做法
    抄老笔记引 /static/tiny_mce/tiny_mce.js 404,编辑器不出现 用 {{ form.media }},实际文件是 tinymce/tinymce.min.js
    from tinymce.models import TinyMCEField ImportError(该类不存在) from tinymce.models import HTMLField
    配 {'theme': 'advanced'} 不报错但完全无效(TinyMCE 7 无此主题) 换成 7.x 认识的 height / toolbar / plugins
    忘了 include("tinymce.urls") 图片浏览/上传功能不可用(编辑器本身还能显示) 根路由挂上,/tinymce/ 返回 404 是正常的
    模板里忘了 safe 过滤器 页面显示 <p>...</p> 源码 输出时写成 {{ content|safe }},同时想清楚 XSS
    上线后编辑器消失 静态文件 404 collectstatic,或确认 STATICFILES_DIRS/STATIC_ROOT

参考

本文结束 感谢您的阅读
正在加载今日诗词....