# Documentation Django 6.0.7

# Formulaires de modèles

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.

## L’API `Meta` des formulaires de modèles

class ModelFormOptions

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 a `django.forms.models.ModelFormOptions` instance.

La structure du formulaire généré peut être adaptée en définissant des options de métadonnées en tant qu’attributs de la classe interne `Meta`. Par exemple :

    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

Les attributs obligatoires sont `model`, et soit `fields`, soit `exclude`. Tous les autres attributs `Meta` sont facultatifs.

Les attributs facultatifs autres que `localized_fields` et `formfield_callback` sont composés par un dictionnaire faisant correspondre un nom de champ de modèle à une valeur. Tout champ non défini dans le dictionnaire va utiliser la valeur par défaut de son type.

Noms de champs non valides

Les noms de champs non valides ou exclus dans un attribut dictionnaire facultatif n’ont aucun effet, puisque les champs non inclus ne sont pas accédés.

Attributs de classe Meta non valides

Vous pouvez définir n’importe quel attribut sur une classe `Meta`. Les noms d’attributs incorrects ne génèrent pas d’erreur.

### `error_messages`

ModelFormOptions.error_messages

  Un dictionnaire faisant correspondre un nom de champ de modèle à un dictionnaire de clés de messages d’erreur (`null`, `blank`, `invalid`, `unique`, etc.) correspondant à des messages d’erreur personnalisés.

  Lorsque un champ n’est pas indiqué, Django se rabat d’abord sur les messages d’erreur définis dans l’attribut `django.db.models.Field.error_messages` de ce champ de modèle, puis sur les messages d’erreur par défaut de ce type de champ.

### `exclude`

ModelFormOptions.exclude

  Un tuple ou une liste de noms de champ de `model` à exclure du formulaire.

  Il est obligatoire de définir `fields` ou `exclude`. Si aucun des deux n’est défini, une exception `ImproperlyConfigured` sera générée. Si attr:~ModelFormOptions.exclude est défini et que `fields` ne l’est pas, tous les champs du modèle sont inclus dans le formulaire, sauf ces champs exclus.

### `field_classes`

ModelFormOptions.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.

  Lorsque un champ n’est pas indiqué, Django se rabat sur la classe de champ par défaut du champ de modèle.

### `fields`

ModelFormOptions.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`

ModelFormOptions.formfield_callback

  Une fonction ou autre objet exécutable acceptant un champ de modèle et renvoyant un objet `django.forms.Field`.

### `help_texts`

ModelFormOptions.help_texts

  Un dictionnaire faisant correspondre un nom de champ de modèle à un texte d’aide.

  Lorsque un champ n’est pas indiqué, Django se rabat sur la valeur `help_text` de ce champ de modèle.

### `labels`

ModelFormOptions.labels

  Un dictionnaire faisant correspondre des noms de champs de modèles à une chaîne qui sera l’étiquette du champ de formulaire.

  Lorsque un champ n’est pas indiqué, Django se rabat sur la valeur `verbose_name` de ce champ de modèle, puis sur le nom d’attribut du champ.

### `localized_fields`

ModelFormOptions.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`

ModelFormOptions.model

  Required. The `django.db.models.Model` to be used for the `ModelForm`.

### `widgets`

ModelFormOptions.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`.

## Model form factory functions

### `modelform_factory`

modelform_factory(model, form=ModelForm, fields=None, exclude=None, formfield_callback=None, widgets=None, localized_fields=None, labels=None, help_texts=None, error_messages=None, field_classes=None)

  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`

modelformset_factory(model, form=ModelForm, formfield_callback=None, formset=BaseModelFormSet, extra=1, can_delete=False, can_order=False, max_num=None, fields=None, exclude=None, widgets=None, validate_max=False, localized_fields=None, labels=None, help_texts=None, error_messages=None, min_num=None, validate_min=False, field_classes=None, absolute_max=None, can_delete_extra=True, renderer=None, edit_only=False)

  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`

inlineformset_factory(parent_model, model, form=ModelForm, formset=BaseInlineFormSet, fk_name=None, fields=None, exclude=None, extra=3, can_order=False, can_delete=True, max_num=None, formfield_callback=None, widgets=None, validate_max=False, localized_fields=None, labels=None, help_texts=None, error_messages=None, min_num=None, validate_min=False, field_classes=None, absolute_max=None, can_delete_extra=True, renderer=None, edit_only=False)

  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.