Vérifié pour : django-unfold 0.104.1
Documentation : https://unfoldadmin.com/docs/ , https://github.com/unfoldadmin/django-unfold
Dépendances : aucune. Lié : unfold-installation, unfold-modeladmin, unfold-settings, unfold-navigation.
Noyau Unfold — Modèle mental et routage
Objectif
Établir le bon modèle mental pour le travail avec Unfold : Unfold est une couche de restylage et d'amélioration au-dessus de django.contrib.admin, pas un remplacement. Presque tout ce que fait Unfold est une administration Django avec de nouveaux templates (Tailwind), un dictionnaire de paramètres et des fonctionnalités optionnelles supplémentaires (actions, filtres, onglets, composants, palette de commandes).
Un agent qui internalise les règles de stratification ci-dessous n'attribuera pas mal les fonctionnalités, ne combattra pas les mécanismes de Django et n'inventera pas de configuration.
Règles de stratification
Chaque compétence appartient exactement à une couche :
| Couche | Ce qu'elle couvre | Exemples |
|---|---|---|
[DJANGO] | Mécanismes standard de l'admin — Unfold ne change que l'apparence | list_display, search_fields, fieldsets, inlines, get_queryset(), has_*_permission, menu déroulant des actions, autocomplete_fields, raw_id_fields, pagination de la liste |
[UNFOLD] | Ajouts officiels d'Unfold — dictionnaire de paramètres, applications contrib, décorateurs, composants, mixins | UNFOLD = {...}, unfold.admin.ModelAdmin, @display, @action, unfold.contrib.filters, UnfoldModelAdminViewMixin, BaseComponent, InfinitePaginator, actions_list/row/detail/submit_line, onglets, palette de commandes |
[CUSTOM] | Code au niveau du projet que l'agent écrit | Surcharge de templates/admin/index.html, construction Tailwind, vues personnalisées avec formulaires, couches service/queryset, composants personnalisés |
[STUDIO] | Compétences du plugin payant Unfold Studio | Mise en page en boîte, en-tête fixe, barre latérale minimale, barre latérale sombre forcée, bannière, navigation imbriquée, templates de tableau de bord. Voir la compétence unfold-studio pour les équivalents d'API publique. |
Règle : attribuer une fonctionnalité à la couche la plus basse qui la fournit. Si le Django pur le fait, recommander le Django pur.
Table de routage (quel mécanisme pour quel besoin)
| L'utilisateur veut | Mécanisme | Compétence |
|---|---|---|
| CRUD pour un modèle | ModelAdmin (Django) | unfold-modeladmin |
| Opération en masse sur les lignes sélectionnées | actions (menu déroulant Django) ou actions_list d'Unfold | unfold-actions |
| Opération sur une ligne depuis la liste | actions_row | unfold-actions |
| Opération sur un objet depuis sa page de détail | actions_detail | unfold-actions |
| Bouton supplémentaire en mode sauvegarde sur le formulaire de modification | actions_submit_line | unfold-actions |
| Boîte de dialogue de confirmation avant une action | @action(dialog={...}) | unfold-actions |
| Panneau de filtre latéral sur la liste des modifications | list_filter (+ classes de filtre Unfold) | unfold-filters |
| Champ de recherche sur la liste des modifications | search_fields (Django) | unfold-modeladmin |
| Marque/titre/logo global | Paramètres UNFOLD | unfold-settings |
| Menu latéral avec icônes/badges | UNFOLD["SIDEBAR"] | unfold-navigation |
| Onglets supplémentaires au-dessus de la liste/du formulaire de modification | UNFOLD["TABS"] | unfold-tabs |
| Onglets à l'intérieur du formulaire de modification | fieldsets classe "tab", inline tab = True | unfold-tabs |
| Page non-CRUD (analytiques, assistant) | vue d'administration personnalisée (UnfoldModelAdminViewMixin) | unfold-custom-pages |
| Page d'accueil de l'admin avec cartes/graphiques | DASHBOARD_CALLBACK + surcharge de templates/admin/index.html, ou page personnalisée | unfold-dashboard |
| Objets liés sur le formulaire de modification | inlines (Django ; classes de base Unfold) | unfold-inlines |
| Regroupement de champs sur le formulaire de modification | fieldsets (Django ; Unfold ajoute des classes d'onglets) | unfold-modeladmin, unfold-tabs |
| Liste de champs répétable et compacte | ArrayWidget | unfold-fields |
| Édition de texte enrichi | WysiwygWidget | unfold-fields |
| Changement visuel de couleur/thème | UNFOLD["COLORS"], BORDER_RADIUS, THEME | unfold-theming |
| Tout ce qui dépasse visuellement les paramètres | Surcharge Tailwind/template | unfold-tailwind |
| Tableau volumineux à pagination lente | InfinitePaginator | unfold-performance |
| Données du modèle dans la palette cmd+K | UNFOLD["COMMAND"] | unfold-navigation |
| Tableaux d'enregistrements liés dans les lignes de la liste (extensibles) | list_sections avec TableSection/TemplateSection | unfold-modeladmin |
| Liste de modifications secondaire sur le formulaire de modification | change_form_datasets (BaseDataset) | unfold-modeladmin |
Quand la configuration ne suffit PAS (implémentation personnalisée nécessaire) :
- Tout ce qui implique un formulaire + POST qui n'est pas une boîte de dialogue d'action → page personnalisée (
unfold-custom-pages). - Tableau de bord plus riche que les composants → surcharge du template du tableau de bord + Tailwind (
unfold-dashboard). - Effets visuels non exposés comme paramètres → Tailwind CSS ou surcharge de template (
unfold-tailwind,unfold-studio). - Logique métier au-delà de simples mutations → couche de service, jamais les méthodes de ModelAdmin (
unfold-production).
Règles d'or
- Chaque classe d'administration doit hériter de
unfold.admin.ModelAdmin(et chaque inline deunfold.admin.TabularInline/StackedInline) sinon les pages s'affichent sans style. Les ModelAdmins tiers nécessitent une ré-enregistrement avec les bases Unfold. "unfold"doit être placé avantdjango.contrib.admindansINSTALLED_APPS. Les applications contrib (unfold.contrib.filters,unfold.contrib.forms,unfold.contrib.inlines) viennent immédiatement après.- Unfold ne remplace pas les URLs de l'admin, le chemin des templates (
admin/base_site.htmlles extensions fonctionnent) ou les mécanismes de permissions de Django — étendre, ne pas combattre. - Ne jamais coder en dur les éléments internes d'Unfold (noms de templates au-delà des composants documentés, balises de template privées) ; utiliser uniquement les paramètres/classes documentés.
- La logique métier ne vit pas dans ModelAdmin. ModelAdmin est une couche HTTP/permissions au-dessus d'une couche de service. Voir
unfold-production. - Unfold évolue rapidement ; tout comportement inattendu → consulter
docs/version-notes.mdet la documentation actuelle avant de déboguer plus en profondeur.
Faits de version (vérifiés)
- Version PyPI actuelle :
0.104.1(cette suite vérifiée pour celle-ci). - Nécessite Python ≥3.12, Django ≥5.2 (
requires_dist: django>=5.2). - Tailwind v4 depuis 0.56.0 (a cassé les feuilles de style personnalisées v3).
- Unfold fonctionne aux côtés de l'admin par défaut ; adoption incrémentielle possible.
Compétences liées
Charger unfold-installation pour les tâches de configuration ; tout le reste est acheminé à partir du tableau ci-dessus.