Django Unfold 技能指南

Django Unfold 是一个基于 Tailwind CSS 构建的现代化 Django 后台主题。它是 django.contrib.admin 的即插即用增强方案——完全兼容所有原生 Django Admin 模式，同时新增了 UI 组件与面向开发者的功能特性。

当前稳定版本：0.90.x（v0.90 起要求 Django 5.0+；已移除对 Django 4.2 的支持）

⚠️ 关键规则 —— 务必始终遵守

规则 1：每个 ModelAdmin 必须继承自 unfold.admin.ModelAdmin

# ✅ 正确
from unfold.admin import ModelAdmin

@admin.register(MyModel)
class MyModelAdmin(ModelAdmin):
    pass

# ❌ 错误 —— 将丢失全部样式与 Unfold 功能
from django.contrib.admin import ModelAdmin  # 切勿使用此基类

规则 2：INSTALLED_APPS 加载顺序 —— "unfold" 必须位于 "django.contrib.admin" 之前

INSTALLED_APPS = [
    "unfold",                           # 必须置顶
    "unfold.contrib.filters",           # 可选：高级筛选器
    "unfold.contrib.forms",             # 可选：ArrayWidget、WysiwygWidget、crispy
    "unfold.contrib.inlines",           # 可选：NonrelatedInline
    "unfold.contrib.import_export",     # 可选：django-import-export
    "unfold.contrib.simple_history",    # 可选：django-simple-history
    "unfold.contrib.guardian",          # 可选：django-guardian
    "unfold.contrib.constance",         # 可选：django-constance
    "unfold.contrib.location_field",    # 可选：django-location-field
    "django.contrib.admin",             # 必须置于 unfold 之后
]

规则 3：Inline 类也需使用 Unfold 提供的基类

from unfold.admin import StackedInline, TabularInline  # 不要使用 django.contrib.admin 中的类

规则 4：User 与 Group 模型需手动重新注册 —— 详见 references/installation.md

核心 ModelAdmin 配置项参考

from unfold.admin import ModelAdmin
from unfold.contrib.forms.widgets import ArrayWidget, WysiwygWidget
from django.db import models

@admin.register(MyModel)
class MyModelAdmin(ModelAdmin):
    # ── 列表页布局 ──────────────────────────────────────────────────
    list_fullwidth = False               # 展开至全屏宽度
    list_filter_sheet = True             # 筛选器以底部抽屉形式展示（False 表示侧边栏）
    list_filter_submit = False           # 在筛选面板中显示“应用”按钮
    list_horizontal_scrollbar_top = False
    list_disable_select_all = False

    # ── 编辑表单用户体验 ────────────────────────────────────────────
    compressed_fields = True             # 紧凑字段显示模式
    warn_unsaved_form = True             # 离开未保存表单前发出警告
    show_add_link = True                 # 显示“添加”按钮
    change_form_show_cancel_button = False

    # 自定义模板注入（HTML 片段，非完整模板）
    change_form_before_template = "myapp/before_form.html"    # 表单内部顶部
    change_form_after_template = "myapp/after_form.html"      # 表单内部底部
    change_form_outer_before_template = "myapp/outer_top.html"
    change_form_outer_after_template = "myapp/outer_bottom.html"

    # ── 只读字段后处理 ─────────────────────────────────────────────
    readonly_preprocess_fields = {
        "html_field": "html.unescape",
        "text_field": lambda content: content.strip(),
    }

    # ── 表单控件覆盖 ───────────────────────────────────────────────
    formfield_overrides = {
        models.TextField: {"widget": WysiwygWidget},
        # ArrayField: {"widget": ArrayWidget},  # 适用于 PostgreSQL ArrayField
    }

    # ── 操作项（共 5 种类型）——详见 references/actions.md ───────────
    actions_list = []        # 列表页顶部（全局操作）
    actions_row = []         # 列表页每行右侧（行级操作）
    actions_detail = []      # 编辑表单页头部区域（详情操作）
    actions_submit_line = [] # 编辑表单页保存按钮附近（提交行操作）

    # ── 条件字段 —— 详见 references/forms-fields.md ────────────────
    conditional_fields = {
        "field_name": "other_field == 'value'",  # Alpine.js 表达式
    }

    # ── 可展开行区块 —— 详见 references/forms-fields.md ────────────
    list_sections = []   # [SectionClass, ...]

    # ── 编辑表单数据集 —— 详见 references/forms-fields.md ──────────
    change_form_datasets = []  # [DatasetClass, ...]

@display 装饰器

务必始终使用 unfold.decorators.display，而非 Django 内置版本。

from unfold.decorators import display

class OrderAdmin(ModelAdmin):
    list_display = ["show_customer", "show_status", "show_priority"]

    # 两行单元格：主标题 + 副标题
    @display(header=True)
    def show_customer(self, obj):
        return obj.full_name, obj.email   # 元组格式：(主内容, 副标题)

    # 根据字段值映射为带颜色的状态徽章
    @display(
        description="状态",
        ordering="status",
        label={
            "PENDING":   "warning",   # 橙色
            "ACTIVE":    "info",      # 蓝色
            "COMPLETED": "success",   # 绿色
            "FAILED":    "danger",    # 红色
        },
    )
    def show_status(self, obj):
        return obj.status

    # 布尔值标签（使用默认颜色）
    @display(description="VIP", label=True)
    def show_priority(self, obj):
        return obj.is_vip

→ 完整的 @display 与 @action 装饰器文档，请参阅：references/decorators.md

参考文档 —— 各文件适用场景

在实现某类功能前，请先阅读对应参考文档。 每个参考文档均明确标注了与其关联的其他文件路径。

常见陷阱

• 生产环境缺失样式 → 运行 collectstatic
• Unfold ≥ 0.56 版本出现 Tailwind 冲突 → 不要加载 Tailwind 3 的 CSS 文件；请改用 UNFOLD["COLORS"] 或升级至 Tailwind 4
• 自定义页面未出现在侧边栏 → 需手动添加至 UNFOLD["SIDEBAR"]["navigation"]
• 第三方 Admin 页面未启用 Unfold 样式（如 celery-beat 等）→ 需先注销再使用 unfold.admin.ModelAdmin 重新注册
• 对 Dataset 使用 list_filter → 不被支持；请改用 get_queryset() 实现过滤逻辑
• Django 4.2 → Unfold v0.90+ 已不再支持