Django 集成百度 UEditor 实现富文本编辑功能
在 Django 项目中集成富文本编辑器是内容管理系统（CMS）开发的常见需求。由于 Django 自身未提供开箱即用的可视化编辑组件，开发者通常需引入第三方解决方案。百度开源的 UEditor 是一个成熟、功能丰富的前端富文本编辑器，而 DjangoUeditor 则是其官方推荐的 Django 封装库，支持无缝嵌入模型字段、表单控件及后台管理界面。
安装与初始化
由于当前主流版本的 DjangoUeditor（如基于 Django 4.x 的分支）存在兼容性问题，建议采用源码方式集成：
- 从 GitHub 获取维护活跃的分支（例如
twz915/DjangoUeditor3），解压后提取DjangoUeditor/目录； - 在项目根目录下新建
extra_apps/文件夹，并将其标记为源码根路径（PyCharm 中右键 → Mark Directory as → Sources Root）； - 将解压得到的
DjangoUeditor子目录复制至extra_apps/； - 在
settings.py中添加路径注册：
import os
import sys
BASE_DIR = Path(__file__).resolve().parent.parent.parent
sys.path.insert(0, os.path.join(BASE_DIR, 'extra_apps'))配置与注册
在 INSTALLED_APPS 中启用模块：
INSTALLED_APPS = [
# ... 其他应用
'DjangoUeditor',
]在主路由文件中挂载上传接口：
from django.urls import include, path
urlpatterns = [
# ... 其他路由
path('api/ueditor/', include('DjangoUeditor.urls')),
]模型字段定义
使用 UEditorField 替代原生 TextField，支持高度定制化配置：
from DjangoUeditor.models import UEditorField
from django.db import models
class BlogPost(models.Model):
headline = models.CharField(max_length=200, verbose_name="标题")
publish_time = models.DateTimeField(auto_now_add=True, verbose_name="发布时间")
body = UEditorField(
verbose_name="正文",
width=720,
height=480,
toolbars='full',
imagePath='uploads/images/%(basename)s_%(datetime)s.%(extname)s',
filePath='uploads/files/%(filename)s',
upload_settings={
'imageMaxSize': 2048000,
'fileMaxSize': 10485760,
'imageAllowFiles': ['.png', '.jpg', '.jpeg', '.gif', '.webp'],
},
settings={
'autoHeightEnabled': False,
'initialFrameHeight': 400,
'enableAutoSave': False,
}
)
class Meta:
verbose_name = "博客文章"
verbose_name_plural = verbose_name媒体资源处理
为支持图片与附件上传，需配置媒体文件服务：
# settings.py
MEDIA_URL = '/media/'
MEDIA_ROOT = BASE_DIR / 'media'# urls.py（仅开发环境）
from django.conf import settings
from django.conf.urls.static import static
urlpatterns += static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)表单集成
通过 ModelForm 自动渲染富文本控件：
from django import forms
from .models import BlogPost
class BlogPostForm(forms.ModelForm):
class Meta:
model = BlogPost
fields = ['headline', 'body']
widgets = {
'body': forms.Textarea(attrs={'class': 'hidden'}),
}模板中务必引入 {{ form.media }} 以加载 UEditor 所需的 JS/CSS 资源：
<form method="post">
{% csrf_token %}
{{ form.media }} <!-- 关键：注入编辑器依赖 -->
{{ form.as_table }}
<button type="submit">保存</button>
</form>后台管理适配
在 admin.py 中注册模型即可获得富文本编辑能力：
from django.contrib import admin
from .models import BlogPost
@admin.register(BlogPost)
class BlogPostAdmin(admin.ModelAdmin):
list_display = ('headline', 'publish_time')
search_fields = ('headline', 'body')高级定制选项
可通过 command 参数扩展工具栏功能，例如添加自定义按钮：
from DjangoUeditor.commands import UEditorButtonCommand
class InsertTimestampButton(UEditorButtonCommand):
def onClick(self):
return """
const now = new Date().toLocaleString('zh-CN');
editor.execCommand('inserthtml', `<p>插入时间：${now}</p>`);
"""
# 在字段定义中引用
body = UEditorField(
# ... 其他参数
command=[InsertTimestampButton(uiName='insertTime', title='插入当前时间')]
)事件监听亦可通过继承 UEditorEventHandler 实现，例如响应内容变更时触发校验逻辑。
全局配置统一管理
在 settings.py 中设置 UEDITOR_SETTINGS 字典，覆盖所有 UEditorField 实例的默认行为：
UEDITOR_SETTINGS = {
"config": {
"toolbar": ["fullscreen", "source", "|", "bold", "italic"],
"initialFrameWidth": "100%",
"wordCount": True,
"maximumWords": 10000,
},
"upload": {
"imagePathFormat": "uploads/images/{yyyy}{mm}{dd}/{time}{rand:6}",
"scrawlPathFormat": "uploads/scrawls/{yyyy}{mm}{dd}/{time}{rand:6}",
}
}