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.pysettings.py 1
2
3
4
5
6
7
8
9
10INSTALLED_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生成的写法。
- 应用名按 PEP8 全小写(老笔记写的是
-
末尾加编辑器配置
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
10from 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
2python manage.py makemigrations
python manage.py migrate
-
-
注册到 admin
myapp/admin.py 1
2
3
4
5from django.contrib import admin
from myapp.models import Article
admin.site.register(Article) -
根路由里挂上它的 URL
project/urls.py 1
2
3
4
5
6
7from 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
9from 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
14from 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
<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="{"selector": "#id_content", ...}"
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。
- 上面两个 JS 是从
显示富文本内容时的安全边界
-
库里存的是 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.js404,编辑器不出现 用 {{ form.media }},实际文件是tinymce/tinymce.min.jsfrom tinymce.models import TinyMCEFieldImportError(该类不存在)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
参考
- django-tinymce:
HTMLField、TINYMCE_DEFAULT_CONFIG、tinymce.urls的出处。 - TinyMCE 7 配置参考:
menubar、plugins、toolbar、valid_elements等有效键。 - Django:Working with form widgets / Media:
{{ form.media }}的机制。 - Django 模板:
safe:关掉自动转义的官方说明与 XSS 警告。