La référence de l’API des formulaires de modèles ModelForm. Pour du contenu d’initiation au sujet de leur utilisation, consultez le guide thématique Création de formulaires à partir de modèles.
Meta des formulaires de modèles¶The _meta API is used to build forms that reflect a Django model. It is
accessible through the _meta attribute of each model form, and is an
django.forms.models.ModelFormOptions instance.
The structure of the generated form can be customized by defining metadata
options as attributes of an inner Meta class. For example:
from django.forms import ModelForm
from myapp.models import Book
class BookForm(ModelForm):
class Meta:
model = Book
fields = ["title", "author"]
help_texts = {
"title": "The title of the book",
"author": "The author of the book",
}
# ... other attributes
Required attributes are model, and either
fields or exclude. All
other Meta attributes are optional.
Optional attributes, other than localized_fields and
formfield_callback, expect a dictionary that maps a
model field name to a value. Any field that is not defined in the dictionary
falls back to the field’s default value.
Invalid field names
Invalid or excluded field names in an optional dictionary attribute have no effect, since fields that are not included are not accessed.
error_messages¶A dictionary that maps a model field name to a dictionary of error message
keys (null, blank, invalid, unique, etc.) mapped to custom
error messages.
When a field is not specified, Django will fall back on the error messages
defined in that model field’s django.db.models.Field.error_messages
and then finally on the default error messages for that field type.
exclude¶A tuple or list of model field names to be
excluded from the form.
Either fields or
exclude must be set. If neither are set, an
ImproperlyConfigured exception will be
raised. If exclude is set and
fields is unset, all model fields, except for
those specified in exclude, are included in the
form.
field_classes¶A dictionary that maps a model field name to a Field
class, which overrides the form_class used in the model field’s
Field.formfield() method.
When a field is not specified, Django will fall back on the model field’s default field class.
fields¶A tuple or list of model field names to be
included in the form. The value '__all__' can be used to specify that
all fields should be included.
If any field is specified in exclude, this will
not be included in the form despite being specified in
fields.
Either fields or
exclude must be set. If neither are set, an
ImproperlyConfigured exception will be
raised.
formfield_callback¶A function or callable that takes a model field and returns a
django.forms.Field object.
help_texts¶labels¶A dictionary that maps a model field names to a label string.
When a field is not specified, Django will fall back on that model field’s
verbose_name and then the field’s attribute
name.
localized_fields¶A tuple or list of model field names to be
localized. The value '__all__' can be used to specify that all fields
should be localized.
By default, form fields are not localized, see enabling localization of fields for more details.
model¶Required. The django.db.models.Model to be used for the
ModelForm.
widgets¶A dictionary that maps a model field name to a
django.forms.Widget.
When a field is not specified, Django will fall back on the default widget
for that particular type of django.db.models.Field.
modelform_factory¶Renvoie une classe ModelForm pour le modèle donné. Le paramètre facultatif form permet d’indiquer une classe de base pour la construction du ModelForm.
fields est une liste facultative de noms de champs. Quand elle est présente, seuls les champs de cette liste seront inclus dans le formulaire renvoyé.
exclude est une liste facultative de noms de champs. Quand elle est présente, les champs de cette liste sont exclus du formulaire renvoyé, même s’ils figurent dans le paramètre fields.
formfield_callback est un objet exécutable acceptant un champ de modèle et renvoyant un champ de formulaire.
widgets est un dictionnaire faisant correspondre des noms de champs de modèle à des composants de formulaires.
localized_fields est une liste de noms de champs devant être régionalisés.
labels est un dictionnaire faisant correspondre des noms de champs de modèle à des étiquettes.
help_texts est un dictionnaire faisant correspondre des noms de champs de modèle à des textes d’aide.
error_messages est un dictionnaire faisant correspondre des noms de champs de modèle à des dictionnaires de messages d’erreur.
field_classes est un dictionnaire faisant correspondre des noms de champs de modèle à une classe de champ de formulaire.
Voir Fonction de fabrique de ModelForm pour des exemples d’utilisation.
Vous devez définir explicitement la liste des champs, soit par les paramètres nommés fields ou exclude, soit par les attributs de même nom de la classe interne de formulaire Meta. Voir Sélection des champs à utiliser pour plus d’informations. En omettant toute définition de champs à utiliser, cela aboutira à une exception ImproperlyConfigured.
modelformset_factory¶Renvoie une classe FormSet pour la classe de modèle donnée.
Les paramètres model, form, fields, exclude, formfield_callback, widgets, localized_fields, labels, help_texts, error_messages et field_classes sont tous transmis à modelform_factory().
Les paramètres formset, extra, can_delete, can_order, max_num, validate_max, min_num, validate_min, absolute_max, can_delete_extra et renderer sont transmis à formset_factory(). Voir Jeux de formulaires pour plus de détails.
L’argument edit_only permet d’empêcher la création de nouveaux objets.
Voir Formulaires groupés de modèles pour des exemples d’utilisation.
inlineformset_factory¶Renvoie un InlineFormSet en utilisant modelformset_factory() avec les valeurs par défaut formset=BaseInlineFormSet, can_delete=True et extra=3.
Si le modèle possède plus d’une clé étrangère ForeignKey vers parent_model, vous devez renseigner le paramètre fk_name.
Voir Sous-formulaires groupés pour des exemples d’utilisation.
déc. 03, 2025