django-unfold-Kenntnisse

Verifiziert für: django-unfold 0.104.1

Dokumentation: https://unfoldadmin.com/docs/ , https://github.com/unfoldadmin/django-unfold

Abhängigkeiten: keine. Verwandt: unfold-installation, unfold-modeladmin, unfold-settings, unfold-navigation.

Unfold Core — Mentales Modell & Routing

Zweck

Das richtige mentale Modell für die Arbeit mit Unfold etablieren: Unfold ist eine optische Neugestaltungs- und Erweiterungsschicht auf django.contrib.admin, kein Ersatz. Nahezu alles, was Unfold macht, ist Django Admin mit neuen Vorlagen (Tailwind), einem Einstellungswörterbuch und zusätzlichen optionalen Funktionen (Aktionen, Filter, Tabs, Komponenten, Befehlspalette).

Ein Agent, der die untenstehenden Schichtenregeln verinnerlicht, wird keine Funktionen falsch zuordnen, gegen Django-Mechaniken kämpfen oder Konfigurationen erfinden.

Schichtenregeln

Jede Fähigkeit gehört genau zu einer Schicht:

Schicht	Abgedeckter Bereich	Beispiele
[DJANGO]	Standard-Admin-Mechanik – Unfold ändert nur das Erscheinungsbild	list_display, search_fields, fieldsets, inlines, get_queryset(), has_*_permission, Aktions-Dropdown, autocomplete_fields, raw_id_fields, Listenseitennummerierung
[UNFOLD]	Offizielle Unfold-Erweiterungen – Einstellungsdict, Contrib-Apps, Dekorateure, Komponenten, Mixins	UNFOLD = {...}, unfold.admin.ModelAdmin, @display, @action, unfold.contrib.filters, UnfoldModelAdminViewMixin, BaseComponent, InfinitePaginator, actions_list/row/detail/submit_line, Tabs, Befehlspalette
[CUSTOM]	Projektcode, den der Agent schreibt	templates/admin/index.html-Überschreibung, Tailwind-Build, benutzerdefinierte Views mit Formularen, Service-/Queryset-Layer, benutzerdefinierte Komponenten
[STUDIO]	Kostenpflichtige Unfold Studio-Plugin-Funktionen	Box-Layout, fixierter Header, minimale Sidebar, erzwungene dunkle Sidebar, Banner, verschachtelte Navigation, Dashboard-Vorlagen. Siehe unfold-studio-Skill für öffentliche API-Äquivalente.

Regel: Ordne eine Funktion der niedrigsten Schicht zu, die sie bereitstellt. Wenn einfaches Django es tut, empfehle einfaches Django.

Routing-Tabelle (welcher Mechanismus für welches Bedürfnis)

Benutzer möchte	Mechanismus	Skill
CRUD für ein Modell	ModelAdmin (Django)	unfold-modeladmin
Massenoperation auf ausgewählten Zeilen	actions (Django-Dropdown) oder Unfold actions_list	unfold-actions
Operation auf einer Zeile aus der Liste	actions_row	unfold-actions
Operation auf einem Objekt von seiner Detailseite	actions_detail	unfold-actions
Zusätzlicher Speichermodus-Button auf dem Änderungsformular	actions_submit_line	unfold-actions
Bestätigungsdialog vor einer Aktion	@action(dialog={...})	unfold-actions
Filter/Seitenpanel auf der Änderungsliste	list_filter (+ Unfold-Filterklassen)	unfold-filters
Suchfeld auf der Änderungsliste	search_fields (Django)	unfold-modeladmin
Globales Branding/Titel/Logo	UNFOLD-Einstellungen	unfold-settings
Seitenmenü mit Symbolen/Badges	UNFOLD["SIDEBAR"]	unfold-navigation
Zusätzliche Tabs über Änderungsliste/Änderungsformular	UNFOLD["TABS"]	unfold-tabs
Tabs innerhalb des Änderungsformulars	fieldsets-"tab"-Klasse, inline tab = True	unfold-tabs
Nicht-CRUD-Seite (Analytik, Assistent)	benutzerdefinierter Admin-View (UnfoldModelAdminViewMixin)	unfold-custom-pages
Admin-Startseite mit Karten/Diagrammen	DASHBOARD_CALLBACK + templates/admin/index.html-Überschreibung, oder benutzerdefinierte Seite	unfold-dashboard
Verwandte Objekte im Änderungsformular	inlines (Django; Unfold-Basisklassen)	unfold-inlines
Feldgruppierung im Änderungsformular	fieldsets (Django; Unfold fügt Tab-Klassen hinzu)	unfold-modeladmin, unfold-tabs
Kompakte wiederholbare Feldliste	ArrayWidget	unfold-fields
Rich-Text-Bearbeitung	WysiwygWidget	unfold-fields
Visuelle Farb-/Themenänderung	UNFOLD["COLORS"], BORDER_RADIUS, THEME	unfold-theming
Alles, was visuell über Einstellungen hinausgeht	Tailwind/Vorlagen-Überschreibung	unfold-tailwind
Große Tabelle, langsame Seitennummerierung	InfinitePaginator	unfold-performance
Modelldaten in der cmd+K-Palette	UNFOLD["COMMAND"]	unfold-navigation
Verwandte-Datensatz-Tabellen in Listenzeilen (erweiterbar)	list_sections mit TableSection/TemplateSection	unfold-modeladmin
Sekundäre Änderungsliste auf dem Änderungsformular	change_form_datasets (BaseDataset)	unfold-modeladmin

Wenn Konfiguration NICHT ausreicht (benutzerdefinierte Implementierung erforderlich):

• Alles mit einem Formular + POST, das kein Aktionsdialog ist → benutzerdefinierte Seite (unfold-custom-pages).
• Dashboard, das komplexer als Komponenten ist → Dashboard-Vorlagen-Überschreibung + Tailwind (unfold-dashboard).
• Visuelle Effekte, die nicht als Einstellungen freigegeben sind → Tailwind CSS oder Vorlagen-Überschreibung (unfold-tailwind, unfold-studio).
• Geschäftslogik, die über einfache Mutationen hinausgeht → Service-Layer, niemals ModelAdmin-Methoden (unfold-production).

Goldene Regeln

1. Jede Admin-Klasse muss unfold.admin.ModelAdmin erben (und jedes Inline unfold.admin.TabularInline/StackedInline), sonst werden Seiten ohne Styling dargestellt. Third-Party-ModelAdmins müssen mit Unfold-Basisklassen neu registriert werden.
2. "unfold" kommt vor django.contrib.admin in INSTALLED_APPS. Contrib-Apps (unfold.contrib.filters, unfold.contrib.forms, unfold.contrib.inlines) kommen unmittelbar danach.
3. Unfold ersetzt keine Admin-URLs, Vorlagenpfade (admin/base_site.html-Erweiterungen funktionieren) oder Djangos Berechtigungsmechanik – erweitere, kämpfe nicht dagegen.
4. Hardcore niemals Unfold-Interna (Vorlagennamen über dokumentierte Komponenten hinaus, private Template-Tags); verwende nur dokumentierte Einstellungen/Klassen.
5. Geschäftslogik lebt nicht in ModelAdmin. ModelAdmin ist eine HTTP-/Berechtigungsschicht über einem Service-Layer. Siehe unfold-production.
6. Unfold ändert sich schnell; bei unerwartetem Verhalten → zuerst docs/version-notes.md und aktuelle Dokumentation prüfen, bevor tiefer debuggst.

Versionsfakten (verifiziert)

• Aktuelle PyPI-Veröffentlichung: 0.104.1 (diese Suite ist dagegen verifiziert).
• Erfordert Python ≥3.12, Django ≥5.2 (requires_dist: django>=5.2).
• Tailwind v4 seit 0.56.0 (hat v3 benutzerdefinierte Stylesheets zerstört).
• Unfold arbeitet neben dem Standard-Admin; inkrementelle Einführung ist in Ordnung.

Verwandte Skills

Lade unfold-installation für Einrichtungsaufgaben; alles andere ergibt sich aus der obigen Tabelle.