Django

Django Unfold 技能 Django Unfold 是一个现代的 Django 管理主题，基于 Tailwind CSS 构建。它是 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", # 必须在后 ] 规则 3：内联也需要 Unfold 基类 from unfold.admin import StackedInline, TabularInline # 不是 django.contrib.admin 规则 4：用户和组模型需要手动重新注册 —— 参见 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 # 布尔标签带默认颜色 @display