Ali-Fani/django-unfold-skills

已驗證版本：django-unfold 0.104.1

文件：https://unfoldadmin.com/docs/ 、 https://github.com/unfoldadmin/django-unfold

相依性：無。相關技能：unfold-installation、unfold-modeladmin、unfold-settings、unfold-navigation。

Unfold 核心 — 心智模型與路由

目的

為 Unfold 相關工作建立正確的心智模型：Unfold 是 django.contrib.admin 的重新樣式化與增強層，並非取代品。Unfold 所做的一切幾乎都是 Django admin 搭配新的模板（Tailwind）、一個設定字典及額外的選擇性功能（動作、篩選器、分頁、元件、命令面板）。

能夠內化以下分層規則的代理，將不會錯誤歸因功能、對抗 Django 機制或憑空創造設定。

分層規則

每個功能都只屬於一個層級：

層級	涵蓋內容	範例
[DJANGO]	標準 admin 機制 — Unfold 僅改變外觀	list_display、search_fields、fieldsets、inlines、get_queryset()、has_*_permission、動作下拉選單、autocomplete_fields、raw_id_fields、列表分頁
[UNFOLD]	Unfold 官方新增功能 — 設定字典、貢獻應用程式、裝飾器、元件、混入類別	UNFOLD = {...}、unfold.admin.ModelAdmin、@display、@action、unfold.contrib.filters、UnfoldModelAdminViewMixin、BaseComponent、InfinitePaginator、actions_list/row/detail/submit_line、分頁、命令面板
[CUSTOM]	代理編寫的專案層級程式碼	templates/admin/index.html 覆寫、Tailwind 建置、含表單的自訂檢視、服務層/查詢集層、自訂元件
[STUDIO]	付費 Unfold Studio 外掛功能	盒狀佈局、固定頂部、最小側邊欄、強制深色側邊欄、橫幅、巢狀導覽、儀表板模板。請參閱 unfold-studio 技能以取得公開 API 等效功能。

規則：將功能歸屬於提供它的最低層級。如果純 Django 就能做到，則建議使用純 Django。

路由表（哪個機制對應哪個需求）

使用者想要	機制	技能
模型的 CRUD	ModelAdmin（Django）	unfold-modeladmin
對選取行執行批次操作	actions（Django 下拉選單）或 Unfold actions_list	unfold-actions
從列表對單一行執行操作	actions_row	unfold-actions
從詳細頁面對單一物件執行操作	actions_detail	unfold-actions
變更表單上的額外儲存模式按鈕	actions_submit_line	unfold-actions
動作前的確認對話框	@action(dialog={...})	unfold-actions
變更列表上的篩選器/側邊面板	list_filter（+ Unfold 篩選器類別）	unfold-filters
變更列表上的搜尋框	search_fields（Django）	unfold-modeladmin
全局品牌/標題/標誌	UNFOLD 設定	unfold-settings
附圖示/徽章的側邊欄選單	UNFOLD["SIDEBAR"]	unfold-navigation
變更列表/變更表單上方的額外分頁	UNFOLD["TABS"]	unfold-tabs
變更表單內部的分頁	fieldsets "tab" 類別、inline tab = True	unfold-tabs
非 CRUD 頁面（分析、精靈）	自訂 admin 檢視（UnfoldModelAdminViewMixin）	unfold-custom-pages
附卡片/圖表的 admin 登陸頁面	DASHBOARD_CALLBACK + 覆寫 templates/admin/index.html 或自訂頁面	unfold-dashboard
變更表單上的關聯物件	inlines（Django；Unfold 基底類別）	unfold-inlines
變更表單欄位分組	fieldsets（Django；Unfold 新增分頁類別）	unfold-modeladmin、unfold-tabs
緊湊的可重複欄位列表	ArrayWidget	unfold-fields
富文本編輯	WysiwygWidget	unfold-fields
視覺色彩/主題變更	UNFOLD["COLORS"]、BORDER_RADIUS、THEME	unfold-theming
超出設定的視覺效果	Tailwind/模板覆寫	unfold-tailwind
大型表格緩慢分頁	InfinitePaginator	unfold-performance
命令面板（cmd+K）中的模型資料	UNFOLD["COMMAND"]	unfold-navigation
變更列表行中的關聯記錄表格（可展開）	搭配 TableSection/TemplateSection 的 list_sections	unfold-modelmain
變更表單上的次要變更列表	change_form_datasets（BaseDataset）	unfold-modelmain

當設定不足時（需要自訂實作）：

• 任何包含表單 + POST 且非動作對話框的項目 → 自訂頁面（unfold-custom-pages）。
• 比元件更豐富的儀表板 → 儀表板模板覆寫 + Tailwind（unfold-dashboard）。
• 未以設定方式暴露的視覺效果 → Tailwind CSS 或模板覆寫（unfold-tailwind、unfold-studio）。
• 超出簡單突變的業務邏輯 → 服務層，絕非 ModelAdmin 方法（unfold-production）。

黃金規則

1. 每個管理類別都必須繼承 unfold.admin.ModelAdmin（而每個 inline 則必須繼承 unfold.admin.TabularInline/StackedInline），否則頁面將無法套用樣式。第三方 ModelAdmin 需要使用 Unfold 基底類別重新註冊。
2. "unfold" 必須放在 INSTALLED_APPS 中的 django.contrib.admin 之前。貢獻應用程式（unfold.contrib.filters、unfold.contrib.forms、unfold.contrib.inlines）應緊接其後。
3. Unfold 不會取代 admin URL、模板路徑（admin/base_site.html 的擴充仍可運作）或 Django 的權限機制 — 應擴充而非對抗。
4. 切勿硬編碼 Unfold 內部細節（超出文件說明元件的模板名稱、私有模板標籤）；僅使用文件說明的設定/類別。
5. 業務邏輯不應存在於 ModelAdmin 中。ModelAdmin 是服務層之上的 HTTP/權限層。請參閱 unfold-production。
6. Unfold 變更速度快；任何非預期行為 → 在深入除錯前，先檢查 docs/version-notes.md 及目前文件。

版本資訊（已驗證）

• 目前 PyPI 版本：0.104.1（本套件已針對此版本驗證）。
• 需要 Python ≥3.12、Django ≥5.2（requires_dist: django>=5.2）。
• 自 0.56.0 起使用 Tailwind v4（破壞了 v3 的自訂樣式表）。
• Unfold 可與預設 admin 並存；可逐步採用。

相關技能

載入 unfold-installation 以進行設定任務；其他所有需求請從上方的路由表查找。