📦 Django
v1.0.0使用 django-unfold（v0.56+）构建高级 Django 管理界面的专家指导。当用户提及 django-unfold、unfold ad... 时调用此技能。
by 详细分析 ▾
运行时依赖
安装命令
点击复制技能文档
Django Unfold Skill Django Unfold 是基于 Tailwind CSS 的 Django 现代后台主题，直接增强 django.contrib.admin——与所有原生 Django 后台模式完全兼容，同时新增 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
# ── 修改表单 UX ─────────────────────────────────────────── 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="Status", ordering="status", label={ "PENDING": "warning", # 橙色 "ACTIVE": "info", # 蓝色 "COMPLETED": "success", # 绿色 "FAILED": "danger", # 红色 }, ) def show_status(self, obj): return obj.status
# 布尔标签，默认颜色 @di