unfold-admin

Django Unfold Admin

基于 Tailwind CSS、HTMX 和 Alpine.js 的现代 Django 管理主题。以精致、功能丰富的界面替代 Django 默认管理界面。

快速开始

安装

# settings.py - unfold MUST be before django.contrib.admin
INSTALLED_APPS = [
    "unfold",
    "unfold.contrib.filters",          # advanced filters
    "unfold.contrib.forms",            # array/wysiwyg widgets
    "unfold.contrib.inlines",          # nonrelated inlines
    "unfold.contrib.import_export",    # styled import/export
    "unfold.contrib.guardian",         # django-guardian integration
    "unfold.contrib.simple_history",   # django-simple-history integration
    "unfold.contrib.constance",        # django-constance integration
    "unfold.contrib.location_field",   # django-location-field integration
    # ...
    "django.contrib.admin",
]

最简管理界面

from unfold.admin import ModelAdmin

@admin.register(MyModel)
class MyModelAdmin(ModelAdmin):
    pass  # inherits Unfold styling

站点配置

替换默认的 AdminSite，或通过设置中的 UNFOLD 字典进行配置。完整的设置参考请参阅 references/configuration.md。

UNFOLD = {
    "SITE_TITLE": "My Admin",
    "SITE_HEADER": "My Admin",
    "SITE_SYMBOL": "dashboard",  # Material Symbols icon name
    "SIDEBAR": {
        "show_search": True,
        "navigation": [
            {
                "title": _("Navigation"),
                "items": [
                    {
                        "title": _("Dashboard"),
                        "icon": "dashboard",
                        "link": reverse_lazy("admin:index"),
                    },
                ],
            },
        ],
    },
}

核心工作流

构建 Unfold 管理界面时，请按以下顺序进行：

1. 配置站点 - UNFOLD 设置字典（品牌标识、侧边栏、主题）
2. 注册模型 - 扩展 unfold.admin.ModelAdmin
3. 增强显示效果 - 使用 @display 装饰器设置列表列
4. 添加操作 - 使用 @action 装饰器添加行、列表、详情和提交操作
5. 配置筛选器 - 用 Unfold 筛选器类替换默认筛选器
6. 覆盖控件 - 通过 formfield_overrides 应用 Unfold 控件
7. 设置内联 - 使用 Unfold 的内联类，并启用标签页、分页和排序
8. 构建仪表板 - 使用 @register_component + BaseComponent 创建 KPI 卡片

ModelAdmin 属性

Unfold 为 Django 的 ModelAdmin 扩展了以下附加属性：

属性	类型	用途
list_fullwidth	bool	使用全宽更改列表（无侧边栏）
list_filter_submit	bool	在筛选器中添加提交按钮
list_filter_sheet	bool	在滑出式面板中显示筛选器
compressed_fields	bool	缩小表单中的字段间距
warn_unsaved_form	bool	离开未保存的表单前发出警告
ordering_field	str	用于拖动排序的字段名称
hide_ordering_field	bool	隐藏排序字段列
list_horizontal_scrollbar_top	bool	在列表顶部显示滚动条
list_disable_select_all	bool	禁用“全选”复选框
change_form_show_cancel_button	bool	在表单上显示取消按钮
actions_list	list	全局更改列表操作
actions_row	list	更改列表中的逐行操作
actions_detail	list	更改表单上的操作
actions_submit_line	list	表单提交区域中的操作
actions_list_hide_default	bool	隐藏默认列表操作
actions_detail_hide_default	bool	隐藏默认详情操作
conditional_fields	dict	控制字段可见性的 JS 表达式
change_form_datasets	list	用于更改表单的 BaseDataset 子类
list_sections	list	用于列表的 TableSection/TemplateSection
list_sections_classes	str	分区的 CSS 网格类
readonly_preprocess_fields	dict	转换只读字段内容
add_fieldsets	list	为添加表单单独设置字段集（类似 UserAdmin）

模板注入点

在更改列表或更改表单之前/之后插入自定义 HTML：

class MyAdmin(ModelAdmin):
    # Changelist
    list_before_template = "myapp/list_before.html"
    list_after_template = "myapp/list_after.html"
    # Change form (inside <form> tag)
    change_form_before_template = "myapp/form_before.html"
    change_form_after_template = "myapp/form_after.html"
    # Change form (outside <form> tag)
    change_form_outer_before_template = "myapp/outer_before.html"
    change_form_outer_after_template = "myapp/outer_after.html"

条件字段

根据其他字段的值显示/隐藏字段（Alpine.js 表达式）：

class MyAdmin(ModelAdmin):
    conditional_fields = {
        "premium_features": "plan == 'PRO'",
        "discount_amount": "has_discount == true",
    }

操作系统

共有 4 种操作类型，每种都有不同的签名。完整参考请参阅 references/actions-filters.md。

from unfold.decorators import action
from unfold.enums import ActionVariant

# List action (no object context)
@action(description=_("Rebuild Index"), icon="sync", variant=ActionVariant.PRIMARY)
def rebuild_index(self, request):
    # process...
    return redirect(request.headers["referer"])

# Row action (receives object_id)
@action(description=_("Approve"), url_path="approve")
def approve_row(self, request, object_id):
    obj = self.model.objects.get(pk=object_id)
    return redirect(request.headers["referer"])

# Detail action (receives object_id, shown on change form)
@action(description=_("Send Email"), permissions=["send_email"])
def send_email(self, request, object_id):
    return redirect(reverse_lazy("admin:myapp_mymodel_change", args=[object_id]))

# Submit line action (receives obj instance, runs on save)
@action(description=_("Save & Publish"))
def save_and_publish(self, request, obj):
    obj.published = True

操作组（下拉菜单）

actions_list = [
    "primary_action",
    {
        "title": _("More"),
        "variant": ActionVariant.PRIMARY,
        "items": ["secondary_action", "tertiary_action"],
    },
]

权限

@action(permissions=["can_export", "auth.view_user"])
def export_data(self, request):
    pass

def has_can_export_permission(self, request):
    return request.user.is_superuser

Display 装饰器

增强 list_display 列。请参阅 references/actions-filters.md。

from unfold.decorators import display

# Colored status labels
@display(description=_("Status"), ordering="status", label={
    "active": "success",    # green
    "pending": "info",      # blue
    "warning": "warning",   # orange
    "inactive": "danger",   # red
})
def show_status(self, obj):
    return obj.status

# Rich header with avatar
@display(description=_("User"), header=True)
def show_header(self, obj):
    return [
        obj.full_name,           # primary text
        obj.email,               # secondary text
        obj.initials,            # badge text
        {"path": obj.avatar.url, "width": 24, "height": 24, "borderless": True},
    ]

# Interactive dropdown
@display(description=_("Teams"), dropdown=True)
def show_teams(self, obj):
    return {
        "title": f"{obj.teams.count()} teams",
        "items": [{"title": t.name, "link": t.get_admin_url()} for t in obj.teams.all()],
        "striped": True,
        "max_height": 200,
    }

# Boolean checkmark
@display(description=_("Active"), boolean=True)
def is_active(self, obj):
    return obj.is_active

筛选器

Unfold 提供高级筛选器类。请参阅 references/actions-filters.md。

from unfold.contrib.filters.admin import (
    TextFilter, RangeNumericFilter, RangeDateFilter, RangeDateTimeFilter,
    SingleNumericFilter, SliderNumericFilter, RelatedDropdownFilter,
    RelatedCheckboxFilter, ChoicesCheckboxFilter, AllValuesCheckboxFilter,
    BooleanRadioFilter, CheckboxFilter, AutocompleteSelectMultipleFilter,
)

class MyAdmin(ModelAdmin):
    list_filter_submit = True  # required for input-based filters
    list_filter = [
        ("salary", RangeNumericFilter),
        ("status", ChoicesCheckboxFilter),
        ("created_at", RangeDateFilter),
        ("category", RelatedDropdownFilter),
        ("is_active", BooleanRadioFilter),
    ]

自定义文本筛选器

class NameFilter(TextFilter):
    title = _("Name")
    parameter_name = "name"

    def queryset(self, request, queryset):
        if self.value() in EMPTY_VALUES:
            return queryset
        return queryset.filter(name__icontains=self.value())

控件

覆盖表单控件以应用 Unfold 样式。请参阅 references/widgets-inlines.md。

from unfold.widgets import (
    UnfoldAdminTextInputWidget, UnfoldAdminSelectWidget, UnfoldAdminSelect2Widget,
    UnfoldBooleanSwitchWidget, UnfoldAdminColorInputWidget,
    UnfoldAdminSplitDateTimeWidget, UnfoldAdminImageFieldWidget,
)
from unfold.contrib.forms.widgets import WysiwygWidget, ArrayWidget

class MyAdmin(ModelAdmin):
    formfield_overrides = {
        models.TextField: {"widget": WysiwygWidget},
        models.ImageField: {"widget": UnfoldAdminImageFieldWidget},
    }

带图标的文本输入框

widget = UnfoldAdminTextInputWidget(attrs={
    "prefix_icon": "search",
    "suffix_icon": "euro",
})

内联

Unfold 内联支持标签页、分页、排序和非关联模型。请参阅 references/widgets-inlines.md。

from unfold.admin import TabularInline, StackedInline
from unfold.contrib.inlines.admin import NonrelatedStackedInline

class OrderItemInline(TabularInline):
    model = OrderItem
    tab = True          # show as tab
    per_page = 10       # paginated
    ordering_field = "weight"  # drag-to-reorder
    hide_title = True
    collapsible = True

字段集标签页

使用 "classes": ["tab"] 将字段集分组到标签页中：

fieldsets = [
    (None, {"fields": ["name", "email"]}),  # always visible
    (_("Profile"), {"classes": ["tab"], "fields": ["bio", "avatar"]}),
    (_("Settings"), {"classes": ["tab"], "fields": ["theme", "notifications"]}),
]

仪表盘组件

构建 KPI 卡片和自定义仪表盘小组件。请参阅 references/dashboard.md。

from unfold.components import BaseComponent, register_component
from django.template.loader import render_to_string

@register_component
class ActiveUsersComponent(BaseComponent):
    def get_context_data(self, **kwargs):
        context = super().get_context_data(**kwargs)
        context["children"] = render_to_string("myapp/kpi_card.html", {
            "total": User.objects.filter(is_active=True).count(),
            "label": "Active Users",
        })
        return context

在设置中配置：

UNFOLD = {
    "DASHBOARD_CALLBACK": "myapp.views.dashboard_callback",
}

分区（变更列表面板）

在变更列表视图中嵌入相关数据面板：

from unfold.sections import TableSection, TemplateSection

class RecentOrdersSection(TableSection):
    related_name = "order_set"
    fields = ["id", "total", "status"]
    height = 380

class ChartSection(TemplateSection):
    template_name = "myapp/chart.html"

class MyAdmin(ModelAdmin):
    list_sections = [RecentOrdersSection, ChartSection]
    list_sections_classes = "lg:grid-cols-2"

数据集（变更表单面板）

在变更表单中嵌入模型列表：

from unfold.datasets import BaseDataset

class RelatedItemsDatasetAdmin(ModelAdmin):
    list_display = ["name", "status"]
    search_fields = ["name"]

class RelatedItemsDataset(BaseDataset):
    model = RelatedItem
    model_admin = RelatedItemsDatasetAdmin
    tab = True  # show as tab

class MyAdmin(ModelAdmin):
    change_form_datasets = [RelatedItemsDataset]

分页器

使用无限滚动分页：

from unfold.paginator import InfinitePaginator

class MyAdmin(ModelAdmin):
    paginator = InfinitePaginator
    show_full_result_count = False
    list_per_page = 20

第三方集成

Unfold 为常见的 Django 包提供带样式的封装。请参阅 references/resources.md 获取完整的设置指南。

包	Unfold 模块	设置
django-import-export	unfold.contrib.import_export	使用 ImportForm、ExportForm、SelectableFieldsExportForm
django-guardian	unfold.contrib.guardian	带样式的 guardian 集成
django-simple-history	unfold.contrib.simple_history	带样式的历史记录集成
django-constance	unfold.contrib.constance	带样式的 constance 配置
django-location-field	unfold.contrib.location_field	位置小组件
django-modeltranslation	兼容	将 TabbedTranslationAdmin 与 ModelAdmin 混用
django-celery-beat	兼容（重新接线）	取消注册 5 个模型，再使用 Unfold 重新注册
django-money	unfold.widgets	UnfoldAdminMoneyWidget
djangoql	兼容	将 DjangoQLSearchMixin 与 ModelAdmin 混用
django-crispy-forms	兼容	提供 Unfold 模板包

# Multiple inheritance - Unfold ModelAdmin always last
@admin.register(MyModel)
class MyAdmin(DjangoQLSearchMixin, SimpleHistoryAdmin, GuardedModelAdmin, ModelAdmin):
    pass

内置模板组件

Unfold 附带可复用的模板组件，可用于仪表盘和自定义页面：

组件	路径	关键变量
卡片	unfold/components/card.html	title、footer、label、icon
柱状图	unfold/components/chart/bar.html	data（JSON）、height、width
折线图	unfold/components/chart/line.html	data（JSON）、height、width
进度条	unfold/components/progress.html	value、title、description
表格	unfold/components/table.html	table、card_included、striped
按钮	unfold/components/button.html	name、href、submit
追踪器	unfold/components/tracker.html	data
队列	unfold/components/cohort.html	data

{% load unfold %}
{% component "MyKPIComponent" %}{% endcomponent %}

用户管理表单

Unfold 提供带样式的 Django 身份验证管理表单：

from unfold.forms import AdminPasswordChangeForm, UserChangeForm, UserCreationForm

@admin.register(User)
class UserAdmin(BaseUserAdmin, ModelAdmin):
    form = UserChangeForm
    add_form = UserCreationForm
    change_password_form = AdminPasswordChangeForm

参考文件

按主题分类的详细文档：

• references/configuration.md - 完整的 UNFOLD 设置字典、侧边栏、标签页、主题、环境、登录
• references/actions-filters.md - 操作类型和签名、显示装饰器、所有筛选器类
• references/widgets-inlines.md - 完整的小组件类列表（35+）、内联变体、非关联内联、表单
• references/dashboard.md - 仪表盘组件、分区、数据集、自定义模板、Tailwind 模式
• references/resources.md - 官方链接、所有第三方集成、常见模式、版本兼容性、Unfold Studio

如需详细配置选项、可用类的完整列表、完整代码示例，或特定功能领域的集成设置指南，请阅读相关参考文件。

重要外部参考资料

资源	URL
文档	https://unfoldadmin.com/docs/
GitHub	https://github.com/unfoldadmin/django-unfold
演示应用（Formula）	https://github.com/unfoldadmin/formula
在线演示	https://demo.unfoldadmin.com
Material Symbols（图标）	https://fonts.google.com/icons

不确定实现模式时，请参考 Formula 演示仓库中的 formula/admin.py 和 formula/settings.py——其中涵盖了几乎所有 Unfold 功能。