---
title: "Formulaires de modèles"
version: 6.1
locale: fr
source: https://docs.djangoproject.com/fr/6.1/ref/forms/models/
canonical: https://djangodocs.dev/fr/6.1/ref/forms/models/
---
# 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](/fr/6.1/topics/forms/modelforms/).

## 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`](#django.forms.ModelFormOptions.model), et soit [`fields`](#django.forms.ModelFormOptions.fields), soit [`exclude`](#django.forms.ModelFormOptions.exclude). Tous les autres attributs `Meta` sont facultatifs.

Les attributs facultatifs autres que [`localized_fields`](#django.forms.ModelFormOptions.localized_fields) et [`formfield_callback`](#django.forms.ModelFormOptions.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`](/fr/6.1/ref/models/fields/#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`](#django.forms.ModelFormOptions.model) à exclure du formulaire.

Il est obligatoire de définir [`fields`](#django.forms.ModelFormOptions.fields) ou [`exclude`](#django.forms.ModelFormOptions.exclude). Si aucun des deux n’est défini, une exception [`ImproperlyConfigured`](/fr/6.1/ref/exceptions/#django.core.exceptions.ImproperlyConfigured) sera générée. Si attr:~ModelFormOptions.exclude est défini et que [`fields`](#django.forms.ModelFormOptions.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`](/fr/6.1/ref/forms/fields/#django.forms.Field)
class, which overrides the `form_class` used in the model field’s
[`Field.formfield()`](/fr/6.1/ref/models/fields/#django.db.models.Field.formfield) method.

Lorsque un champ n’est pas indiqué, Django se rabat sur la [classe de champ par défaut](/fr/6.1/topics/forms/modelforms/#model-form-field-types) du champ de modèle.

### `fields`

#### `ModelFormOptions.fields`

A tuple or list of [`model`](#django.forms.ModelFormOptions.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`](#django.forms.ModelFormOptions.exclude), this will
not be included in the form despite being specified in
[`fields`](#django.forms.ModelFormOptions.fields).

Either [`fields`](#django.forms.ModelFormOptions.fields) or
[`exclude`](#django.forms.ModelFormOptions.exclude) must be set. If neither are set, an
[`ImproperlyConfigured`](/fr/6.1/ref/exceptions/#django.core.exceptions.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`](/fr/6.1/ref/forms/fields/#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`](/fr/6.1/ref/models/fields/#django.db.models.Field.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`](/fr/6.1/ref/models/fields/#django.db.models.Field.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`](#django.forms.ModelFormOptions.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](/fr/6.1/topics/forms/modelforms/#modelforms-enabling-localization-of-fields) for more details.

### `model`

#### `ModelFormOptions.model`

Required. The [`django.db.models.Model`](/fr/6.1/ref/models/instances/#django.db.models.Model) to be used for the
[`ModelForm`](/fr/6.1/topics/forms/modelforms/#django.forms.ModelForm).

### `widgets`

#### `ModelFormOptions.widgets`

A dictionary that maps a model field name to a
[`django.forms.Widget`](/fr/6.1/ref/forms/widgets/#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`](/fr/6.1/ref/models/fields/#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`](/fr/6.1/topics/forms/modelforms/#django.forms.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](/fr/6.1/topics/forms/modelforms/#modelforms-factory) 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](/fr/6.1/topics/forms/modelforms/#modelforms-selecting-fields) pour plus d’informations. En omettant toute définition de champs à utiliser, cela aboutira à une exception [`ImproperlyConfigured`](/fr/6.1/ref/exceptions/#django.core.exceptions.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()`](#django.forms.models.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()`](/fr/6.1/ref/forms/formsets/#django.forms.formsets.formset_factory). Voir [Jeux de formulaires](/fr/6.1/topics/forms/formsets/) pour plus de détails.

L’argument `edit_only` permet [d’empêcher la création de nouveaux objets](/fr/6.1/topics/forms/modelforms/#model-formsets-edit-only).

Voir [Formulaires groupés de modèles](/fr/6.1/topics/forms/modelforms/#model-formsets) 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()`](#django.forms.models.modelformset_factory) avec les valeurs par défaut `formset=`[`BaseInlineFormSet`](/fr/6.1/topics/forms/modelforms/#django.forms.models.BaseInlineFormSet), `can_delete=True` et `extra=3`.

Si le modèle possède plus d’une clé étrangère [`ForeignKey`](/fr/6.1/ref/models/fields/#django.db.models.ForeignKey) vers `parent_model`, vous devez renseigner le paramètre `fk_name`.

Voir [Sous-formulaires groupés](/fr/6.1/topics/forms/modelforms/#inline-formsets) pour des exemples d’utilisation.