--- title: "Champs de formulaires" version: 4.0 locale: fr source: https://docs.djangoproject.com/fr/4.0/ref/forms/fields/ canonical: https://djangodocs.dev/fr/4.0/ref/forms/fields/ --- # Champs de formulaires #### `class Field(**kwargs)` Lorsque vous créez une classe `Form`, la partie la plus importante est de définir les champs du formulaire. Chaque champ possède sa propre logique de validation, ainsi que quelques autres points d’entrée. #### `Field.clean(value)` Même si l’emploi principal des classes `Field` concerne la définition de classes `Form`, il est aussi possible de les instancier et de les utiliser directement pour obtenir une meilleure idée de leur fonctionnement. Chaque instance `Field` possède une méthode `clean()` acceptant un seul paramètre et qui renvoie une valeur « nettoyée » ou qui génère une exception `django.core.exceptions.ValidationError`: ``` >>> from django import forms >>> f = forms.EmailField() >>> f.clean('foo@example.com') 'foo@example.com' >>> f.clean('invalid email address') Traceback (most recent call last): ... ValidationError: ['Enter a valid email address.'] ``` ## Paramètres principaux des champs Chaque constructeur de classe `Field` accepte au moins trois paramètres. Certaines classes acceptent d’autres paramètres spécifiques à la classe, mais ceux qui suivent sont *toujours* acceptés : ### `required` #### `Field.required` Par défaut, chaque classe `Field` suppose qu’une valeur est obligatoire, ce qui fait que si vous ne fournissez pas de valeur (que ce soit `None` ou une chaîne vide(`""`)), `clean()` génère une exception `ValidationError`: ``` >>> from django import forms >>> f = forms.CharField() >>> f.clean('foo') 'foo' >>> f.clean('') Traceback (most recent call last): ... ValidationError: ['This field is required.'] >>> f.clean(None) Traceback (most recent call last): ... ValidationError: ['This field is required.'] >>> f.clean(' ') ' ' >>> f.clean(0) '0' >>> f.clean(True) 'True' >>> f.clean(False) 'False' ``` Pour indiquer qu’un champ n’est *pas* obligatoire, passez `required=False` au constructeur de `Field`: ``` >>> f = forms.CharField(required=False) >>> f.clean('foo') 'foo' >>> f.clean('') '' >>> f.clean(None) '' >>> f.clean(0) '0' >>> f.clean(True) 'True' >>> f.clean(False) 'False' ``` Lorsque `required=False` est défini pour un champ `Field` et que vous fournissez une valeur vide à `clean()`, la valeur renvoyée est une valeur vide *normalisée* et aucune exception `ValidationError` n’est générée. Pour `CharField`, la valeur renvoyée correspond à [`empty_value`](#django.forms.CharField.empty_value) qui est une chaîne vide par défaut. Pour les autres classes `Field`, il peut s’agir de `None` (cela varie en fonction du champ). Les composants des champs de formulaire obligatoires possèdent l’attribut HTML `required`. Il est possible de désactiver cela en définissant l’attribut [`Form.use_required_attribute`](/fr/4.0/ref/forms/api/#django.forms.Form.use_required_attribute) à `False`. L’attribut `required` n’est pas ajouté aux formulaires groupés car la validation des navigateurs n’est pas toujours correcte quand on ajoute ou qu’on supprime de tels formulaires. ### `label` #### `Field.label` Le paramètre `label` permet d’indiquer une étiquette conviviale pour le champ. Cette valeur est utilisée lorsque le champ `Field` est affiché dans un formulaire `Form`. Comme expliqué dans « Affichage des formulaires en HTML » ci-dessus, l’étiquette par défaut d’un champ `Field` est générée à partir du nom de champ en convertissant tous les soulignements en espaces et en mettant en majuscule la première lettre. Donnez une valeur à `label` si ce comportement par défaut ne produit pas un résultat convenable. Voici un exemple complet de formulaire implémentant `label` pour deux de ses champs. Nous avons indiqué `auto_id=False` pour simplifier l’affichage : ``` >>> from django import forms >>> class CommentForm(forms.Form): ... name = forms.CharField(label='Your name') ... url = forms.URLField(label='Your website', required=False) ... comment = forms.CharField() >>> f = CommentForm(auto_id=False) >>> print(f) Your name: Your website: Comment: ``` ### `label_suffix` #### `Field.label_suffix` Le paramètre `label_suffix` permet de surcharger l’attribut [`label_suffix`](/fr/4.0/ref/forms/api/#django.forms.Form.label_suffix) d’un formulaire pour un champ particulier : ``` >>> class ContactForm(forms.Form): ... age = forms.IntegerField() ... nationality = forms.CharField() ... captcha_answer = forms.IntegerField(label='2 + 2', label_suffix=' =') >>> f = ContactForm(label_suffix='?') >>> print(f.as_p())

``` ### `initial` #### `Field.initial` Le paramètre `initial` permet d’indiquer la valeur initiale à utiliser lors de l’affichage HTML du champ dans un formulaire `Form` non lié. Pour indiquer des données initiales dynamiques, voir le paramètre [`Form.initial`](/fr/4.0/ref/forms/api/#django.forms.Form.initial). Le cas d’utilisation typique est lorsque l’on veut afficher un formulaire vierge dans lequel un champ contient initialement une valeur. Par exemple : ``` >>> from django import forms >>> class CommentForm(forms.Form): ... name = forms.CharField(initial='Your name') ... url = forms.URLField(initial='http://') ... comment = forms.CharField() >>> f = CommentForm(auto_id=False) >>> print(f) Name: Url: Comment: ``` Vous vous demandez peut-être pourquoi on ne passe pas simplement un dictionnaire de valeurs initiales dans le paramètre `data` au moment d’afficher le formulaire ? Le problème de cette solution est que cela provoque la validation des données et que le résultat HTML contiendra alors d’éventuelles erreurs de validation : ``` >>> class CommentForm(forms.Form): ... name = forms.CharField() ... url = forms.URLField() ... comment = forms.CharField() >>> default_data = {'name': 'Your name', 'url': 'http://'} >>> f = CommentForm(default_data, auto_id=False) >>> print(f) Name: Url: Comment: ``` C’est pourquoi les valeurs initiales ne sont affichées que pour les formulaires non liés. Pour les formulaires liés, le résultat HTML utilise les données liées. Notez également que les valeurs initiales ne sont *pas* utilisées comme données de repli dans la validation lorsqu’une valeur de champ est manquante. Les valeurs initiales sont *uniquement* destinées à l’affichage initial d’un formulaire : ``` >>> class CommentForm(forms.Form): ... name = forms.CharField(initial='Your name') ... url = forms.URLField(initial='http://') ... comment = forms.CharField() >>> data = {'name': '', 'url': '', 'comment': 'Foo'} >>> f = CommentForm(data) >>> f.is_valid() False # The form does *not* fall back to using the initial values. >>> f.errors {'url': ['This field is required.'], 'name': ['This field is required.']} ``` Au lieu d’une constante, il est aussi possible de transmettre un objet exécutable : ``` >>> import datetime >>> class DateForm(forms.Form): ... day = forms.DateField(initial=datetime.date.today) >>> print(DateForm()) Day: ``` L’objet exécutable ne sera évalué qu’au moment où le formulaire non lié est affiché, et non pas au moment de sa définition. ### `widget` #### `Field.widget` Le paramètre `widget` permet d’indiquer une classe `Widget` à utiliser lors du rendu HTML de ce champ. Voir [Composants de formulaires (« widgets »)](/fr/4.0/ref/forms/widgets/) pour plus d’informations. ### `help_text` #### `Field.help_text` Le paramètre `help_text` vous permet de définir du texte descriptif pour ce champ. S’il est défini, il sera affiché près du champ lorsque celui-ci sera affiché en HTML par l’une des méthodes de raccourci de `Form` (par ex. `as_ul()`). Tout comme l’attribut [`help_text`](/fr/4.0/ref/models/fields/#django.db.models.Field.help_text) d’un champ de modèle, cette valeur n’est pas sujette à l’échappement HTML dans les formulaires générés automatiquement. Voici un exemple complet de formulaire implémentant `help_text` pour deux de ses champs. Nous avons indiqué `auto_id=False` pour simplifier l’affichage : ``` >>> from django import forms >>> class HelpTextContactForm(forms.Form): ... subject = forms.CharField(max_length=100, help_text='100 characters max.') ... message = forms.CharField() ... sender = forms.EmailField(help_text='A valid email address, please.') ... cc_myself = forms.BooleanField(required=False) >>> f = HelpTextContactForm(auto_id=False) >>> print(f.as_table()) Subject:
100 characters max. Message: Sender:
A valid email address, please. Cc myself: >>> print(f.as_ul()))
  • Subject: 100 characters max.
  • Message:
  • Sender: A valid email address, please.
  • Cc myself:
    • >>> print(f.as_p())

    Subject: 100 characters max.

    Message:

    Sender: A valid email address, please.

    Cc myself:

    ``` ### `error_messages` #### `Field.error_messages` Le paramètre `error_messages` permet de redéfinir les messages par défaut que le champ renvoie. Passez un dictionnaire dont les clés correspondent aux messages d’erreur que vous voulez redéfinir. Par exemple, voici le message d’erreur par défaut : ``` >>> from django import forms >>> generic = forms.CharField() >>> generic.clean('') Traceback (most recent call last): ... ValidationError: ['This field is required.'] ``` Et voici un message d’erreur personnalisé : ``` >>> name = forms.CharField(error_messages={'required': 'Please enter your name'}) >>> name.clean('') Traceback (most recent call last): ... ValidationError: ['Please enter your name'] ``` Dans la section [Classes de champs Field intégrées](#built-in-field-classes) ci-dessous, chaque champ `Field` définit les clés de messages d’erreur qu’il utilise. ### `validators` #### `Field.validators` Le paramètre `validators` permet de définir une liste de fonctions de validation pour le champ. Consultez la [documentation des validateurs](/fr/4.0/ref/validators/) pour plus d’informations. ### `localize` #### `Field.localize` Le paramètre `localize` active la régionalisation des données de formulaires, aussi bien au niveau de la saisie que de l’affichage produit. Consultez la documentation sur la [régionalisation de la mise en forme](/fr/4.0/topics/i18n/formatting/) pour plus d’informations. ### `disabled` #### `Field.disabled` Le paramètre booléen `disabled`, lorsqu’il est défini à `True`, désactive un champ de formulaire en utilisant l’attribut HTML `disabled` afin qu’il ne soit pas modifiable par les utilisateurs. Même si quelqu’un forçait la modification de la valeur du champ soumis au serveur, elle serait ignorée en faveur de la valeur fournie initialement au formulaire. ## Contrôle des données de champ modifiées ### `has_changed()` #### `Field.has_changed()` La méthode `has_changed()` est utilisée pour déterminer si la valeur du champ a été modifiée par rapport à sa valeur initiale. Renvoie `True` ou `False`. Consultez la documentation de [`Form.has_changed()`](/fr/4.0/ref/forms/api/#django.forms.Form.has_changed) pour plus de détails. ## Classes de champs `Field` intégrées Bien évidemment, la bibliothèque des formulaires est livrée avec une série de classes `Field` représentant les besoins de validation les plus courants. Cette section décrit chaque champ intégré dans Django. Pour chaque champ, nous indiquons le composant utilisé par défaut quand `widget` n’est pas précisé. Nous indiquons également la valeur renvoyée lorsqu’une valeur vide est fournie (voir la section sur `required` ci-dessus pour comprendre ce que cela signifie). ### `BooleanField` #### `class BooleanField(**kwargs)` - Composant par défaut : [`CheckboxInput`](/fr/4.0/ref/forms/widgets/#django.forms.CheckboxInput) - Valeur vide : `False` - Est normalisé en : une valeur Python `True` ou `False`. - Valide que la valeur est `True` (signifiant par exemple que la case à cocher est cochée) si `required=True` pour ce champ. - Clés de messages d’erreur : `required` > **Note** > > Comme toutes les sous-classes de `Field` héritent `required=True` par défaut, la condition de validation est importante à cet endroit. Si vous souhaitez inclure une valeur booléenne dans un formulaire qui puisse valoir aussi bien `True` que `False` (par exemple une case cochée ou non), vous devez vous rappeler de passer `required=False` au moment de créer le champ `BooleanField`. ### `CharField` #### `class CharField(**kwargs)` - Composant par défaut : [`TextInput`](/fr/4.0/ref/forms/widgets/#django.forms.TextInput) - Valeur vide : ce qui a été indiqué dans [`empty_value`](#django.forms.CharField.empty_value). - Est normalisé en : une chaîne. - Utilise [`MaxLengthValidator`](/fr/4.0/ref/validators/#django.core.validators.MaxLengthValidator) et [`MinLengthValidator`](/fr/4.0/ref/validators/#django.core.validators.MinLengthValidator) si `max_length` et `min_length` sont fournis. Sinon, toutes les entrées sont valides. - Clés de messages d’erreur : `required`, `max_length`, `min_length` Possède quatre paramètres facultatifs liés à la validation : #### `max_length` #### `min_length` Quand ils sont fournis, ces paramètres garantissent que la chaîne de caractères correspond au maximum ou au minimum à la longueur donnée. #### `strip` Si `True` (valeur par défaut), la valeur sera épurée d’éventuelles espaces initiales ou finales. #### `empty_value` La valeur à utiliser pour représenter une valeur vide. Contient une chaîne vide par défaut. ### `ChoiceField` #### `class ChoiceField(**kwargs)` - Composant par défaut : [`Select`](/fr/4.0/ref/forms/widgets/#django.forms.Select) - Valeur vide : `''` (une chaîne vide) - Est normalisé en : une chaîne. - Valide que la valeur donnée existe dans la liste à choix. - Clés de messages d’erreur : `required`, `invalid_choice` Le message d’erreur `invalid_choice` peut contenir `%(value)s`, qui sera remplacé par le choix sélectionné. Accepte un paramètre supplémentaire : #### `choices` Soit un object [itérable](https://docs.python.org/3/glossary.html#term-iterable) de tuples à 2 valeurs à utiliser comme liste de choix pour ce champ, soit des choix d’une [énumération](/fr/4.0/ref/models/fields/#field-choices-enum-types), soit un objet exécutable qui renvoie un tel objet itérable. Ce paramètre accepte les mêmes formats que le paramètre `choices` d’un champ de modèle. Consultez la [documentation des champs de modèles sur les choix](/fr/4.0/ref/models/fields/#field-choices) pour plus de détails. Si le paramètre est un exécutable, il est évalué lors de chaque initialisation du formulaire contenant le champ, en plus de l’évaluation au moment du rendu. Par défaut, c’est une liste vide. ### `DateField` #### `class DateField(**kwargs)` - Composant par défaut : [`DateInput`](/fr/4.0/ref/forms/widgets/#django.forms.DateInput) - Valeur vide : `None` - Est normalisé en : un objet Python `datetime.date`. - Valide que la valeur donnée est un objet `datetime.date`, `datetime.datetime` ou une chaîne mise en forme dans un format de date particulier. - Clés de messages d’erreur : `required`, `invalid` Accepte un paramètre facultatif : #### `input_formats` Une liste de chaînes de format utilisées pour essayer de convertir une chaîne en un objet `datetime.date` valide. Si aucun paramètre `input_formats` n’est indiqué, les formats d’entrée par défaut sont lus dans dans [`DATE_INPUT_FORMATS`](/fr/4.0/ref/settings/#std-setting-DATE_INPUT_FORMATS) si [`USE_L10N`](/fr/4.0/ref/settings/#std-setting-USE_L10N) est `False`, ou dans la clé `DATE_INPUT_FORMATS` de la langue active si la régionalisation est activée. Voir aussi la [régionalisation des formats](/fr/4.0/topics/i18n/formatting/). ### `DateTimeField` #### `class DateTimeField(**kwargs)` - Composant par défaut : [`DateTimeInput`](/fr/4.0/ref/forms/widgets/#django.forms.DateTimeInput) - Valeur vide : `None` - Est normalisé en : un objet Python `datetime.datetime`. - Valide que la valeur donnée est un objet `datetime.datetime`, `datetime.date` ou une chaîne mise en forme dans un format de date/heure particulier. - Clés de messages d’erreur : `required`, `invalid` Accepte un paramètre facultatif : #### `input_formats` Une liste de chaînes de format utilisées pour essayer de convertir une chaîne en un objet `datetime.datetime` valide, en plus des formats ISO 8601. Le champ accepte toujours les chaînes mises en forme selon le format ISO 8601 ou apparenté reconnues par [`parse_datetime()`](/fr/4.0/ref/utils/#django.utils.dateparse.parse_datetime). Voici quelques exemples ``` * '2006-10-25 14:30:59' * '2006-10-25T14:30:59' * '2006-10-25 14:30' * '2006-10-25T14:30' * '2006-10-25T14:30Z' * '2006-10-25T14:30+02:00' * '2006-10-25' ``` Si aucun paramètre `input_formats` n’est indiqué, les formats d’entrée par défaut sont lus dans dans [`DATETIME_INPUT_FORMATS`](/fr/4.0/ref/settings/#std-setting-DATETIME_INPUT_FORMATS) et [`DATE_INPUT_FORMATS`](/fr/4.0/ref/settings/#std-setting-DATE_INPUT_FORMATS) si [`USE_L10N`](/fr/4.0/ref/settings/#std-setting-USE_L10N) est `False`, ou dans les clés `DATETIME_INPUT_FORMATS` et `DATE_INPUT_FORMATS` de la langue active si la régionalisation est activée. Voir aussi la [régionalisation des formats](/fr/4.0/topics/i18n/formatting/). ### `DecimalField` #### `class DecimalField(**kwargs)` - Composant par défaut : [`NumberInput`](/fr/4.0/ref/forms/widgets/#django.forms.NumberInput) lorsque [`Field.localize`](#django.forms.Field.localize) vaut `False`, sinon [`TextInput`](/fr/4.0/ref/forms/widgets/#django.forms.TextInput). - Valeur vide : `None` - Est normalisé en : un objet Python `decimal`. - Valide que la valeur donnée est un nombre décimal. Utilise [`MaxValueValidator`](/fr/4.0/ref/validators/#django.core.validators.MaxValueValidator) et [`MinValueValidator`](/fr/4.0/ref/validators/#django.core.validators.MinValueValidator) si `max_value` et `min_value` sont fournis. Les espaces de début et de fin sont ignorés. - Clés de messages d’erreur : `required`, `invalid`, `max_value`, `min_value`, `max_digits`, `max_decimal_places`, `max_whole_digits` Les messages d’erreur `max_value` et `min_value` peuvent contenir `%(limit_value)s`, qui sera remplacé par la limite concernée. Sur le même principe, les messages d’erreur `max_digits`, `max_decimal_places` et `max_whole_digits` peuvent contenir `%(max)s`. Accepte quatre paramètres facultatifs : #### `max_value` #### `min_value` Ces paramètres contrôlent les intervalles de valeurs autorisées dans le champ et doivent être exprimés en valeurs `decimal.Decimal`. #### `max_digits` Le nombre maximum de chiffres autorisés dans la valeur (avant et après le point décimal, sans tenir compte des zéros initiaux). #### `decimal_places` Le nombre maximal de décimales autorisées. ### `DurationField` #### `class DurationField(**kwargs)` - Composant par défaut : [`TextInput`](/fr/4.0/ref/forms/widgets/#django.forms.TextInput) - Valeur vide : `None` - Est normalisé en : un objet Python [`timedelta`](https://docs.python.org/3/library/datetime.html#datetime.timedelta). - Valide que la valeur donnée est une chaîne qui peut être convertie en une différence de temps `timedelta`. La valeur doit être comprise entre [`datetime.timedelta.min`](https://docs.python.org/3/library/datetime.html#datetime.timedelta.min) et [`datetime.timedelta.max`](https://docs.python.org/3/library/datetime.html#datetime.timedelta.max). - Clés de messages d’erreur : `required`, `invalid`, `overflow`. Accepte tout format que [`parse_duration()`](/fr/4.0/ref/utils/#django.utils.dateparse.parse_duration) peut analyser. ### `EmailField` #### `class EmailField(**kwargs)` - Composant par défaut : [`EmailInput`](/fr/4.0/ref/forms/widgets/#django.forms.EmailInput) - Valeur vide : ce qui a été indiqué dans `empty_value`. - Est normalisé en : une chaîne. - Utilise [`EmailValidator`](/fr/4.0/ref/validators/#django.core.validators.EmailValidator) pour valider que la valeur donnée est une adresse de courriel valide, en utilisant une expression régulière moyennement complexe. - Clés de messages d’erreur : `required`, `invalid` Possède trois paramètres facultatifs `max_length`, `min_length` et `empty_value`, qui fonctionnent exactement comme pour [`CharField`](#django.forms.CharField). ### `FileField` #### `class FileField(**kwargs)` - Composant par défaut : [`ClearableFileInput`](/fr/4.0/ref/forms/widgets/#django.forms.ClearableFileInput) - Valeur vide : `None` - Est normalisé en : un objet `UploadedFile` englobant le contenu du fichier et son nom dans un seul objet. - Peut valider que des données de fichier non vides ont été fournies au formulaire. - Clés de messages d’erreur : `required`, `invalid`, `missing`, `empty`, `max_length` Accepte deux paramètres facultatifs pour la validation, `max_length` et `allow_empty_file`. S’ils sont présents, ils garantissent respectivement que la longueur du nom de fichier ne dépasse pas la longueur indiquée et que la validation passe même quand le contenu du fichier est vide. Pour en savoir plus au sujet de l’objet `UploadedFile`, consultez la [documentation sur les envois de fichiers](/fr/4.0/topics/http/file-uploads/). Lorsque vous utilisez un champ `FileField` dans un formulaire, vous ne devez pas oublier de [lier les données de fichier au formulaire](/fr/4.0/ref/forms/api/#binding-uploaded-files). L’erreur `max_length` porte sur la longueur du nom de fichier. Dans le message d’erreur de cette clé, `%(max)d` sera remplacé par la longueur maximale du nom de fichier et `%(length)d` sera remplacé par la longueur effective du nom de fichier. ### `FilePathField` #### `class FilePathField(**kwargs)` - Composant par défaut : [`Select`](/fr/4.0/ref/forms/widgets/#django.forms.Select) - Valeur vide : `''` (une chaîne vide) - Est normalisé en : une chaîne. - Valide que le choix sélectionné existe dans la liste à choix. - Clés de messages d’erreur : `required`, `invalid_choice` Ce champ permet de choisir parmi des fichiers dans un répertoire désigné. Il accepte cinq paramètres supplémentaires ; seul `path` est obligatoire : #### `path` Le chemin absolu vers le répertoire dont le contenu doit être présent dans la liste. Ce répertoire doit exister. #### `recursive` Si `False` (valeur par défaut), seul le contenu au premier niveau de `path` sera à disposition dans les choix possibles. Si `True`, le répertoire sera parcouru récursivement et tous ses descendants seront inclus dans les choix possibles. #### `match` Un motif d’expression régulière ; seuls les fichiers dont les noms correspondent à cette expression seront disponibles dans la liste à choix. #### `allow_files` Facultatif. Vaut `True` ou `False`. La valeur par défaut est `True`. Indique si les fichiers de l’emplacement spécifié doivent être inclus. Il faut que l’une des deux valeurs, ce champ ou [`allow_folders`](#django.forms.FilePathField.allow_folders), soit `True`. #### `allow_folders` Facultatif. Vaut `True` ou `False`. La valeur par défaut est `False`. Indique si tous les répertoires à l’intérieur de l’emplacement spécifié doivent être inclus. Il faut que l’une des deux valeurs, ce champ ou [`allow_files`](#django.forms.FilePathField.allow_files), soit `True`. ### `FloatField` #### `class FloatField(**kwargs)` - Composant par défaut : [`NumberInput`](/fr/4.0/ref/forms/widgets/#django.forms.NumberInput) lorsque [`Field.localize`](#django.forms.Field.localize) vaut `False`, sinon [`TextInput`](/fr/4.0/ref/forms/widgets/#django.forms.TextInput). - Valeur vide : `None` - Est normalisé en : un objet Python float. - Valide que la valeur donnée est un nombre à virgule. Utilise [`MaxValueValidator`](/fr/4.0/ref/validators/#django.core.validators.MaxValueValidator) et [`MinValueValidator`](/fr/4.0/ref/validators/#django.core.validators.MinValueValidator) si `max_value` et `min_value` sont fournis. Les espaces de début et de fin sont permis, comme pour la fonction `float()` de Python. - Clés de messages d’erreur : `required`, `invalid`, `max_value`, `min_value` Accepte deux paramètres facultatifs pour la validation, `max_value` et `min_value`. Ces paramètres contrôlent l’intervalle des valeurs autorisées dans ce champ. ### `GenericIPAddressField` #### `class GenericIPAddressField(**kwargs)` Un champ contenant soit une adresse IPv4, soit une adresse IPv6. - Composant par défaut : [`TextInput`](/fr/4.0/ref/forms/widgets/#django.forms.TextInput) - Valeur vide : `''` (une chaîne vide) - Est normalisé en : une chaîne. Les adresses IPv6 sont normalisées selon la description ci-dessous. - Valide que la valeur donnée est une adresse IP valide. - Clés de messages d’erreur : `required`, `invalid` La normalisation d’adresse IPv6 respecte la section 2.2 de la [**RFC 4291 Section 2.2**](https://datatracker.ietf.org/doc/html/rfc4291.html#section-2.2), y compris l’utilisation du format IPv4 suggéré dans le 3e paragraphe de cette section, comme `::ffff:192.0.2.0`. Par exemple, `2001:0::0:01` sera normalisé en `2001::1` et `::ffff:0a0a:0a0a` en `::ffff:10.10.10.10`. Tous les caractères sont convertis en minuscules. Accepte deux paramètres facultatifs : #### `protocol` Limite la validité des saisies au protocole indiqué. Les valeurs possibles sont `'both'` (les deux protocoles acceptés, valeur par défaut), `'IPv4'` ou `'IPv6'`. La correspondance n’est pas sensible à la casse. #### `unpack_ipv4` Décode les adresses IPv4 mappées comme `::ffff:192.0.2.1`. Si cette option est activée, cette adresse serait décodée en `192.0.2.1`. L’option est désactivée par défaut. Utilisable uniquement quand `protocol` est défini à `'both'`. ### `ImageField` #### `class ImageField(**kwargs)` - Composant par défaut : [`ClearableFileInput`](/fr/4.0/ref/forms/widgets/#django.forms.ClearableFileInput) - Valeur vide : `None` - Est normalisé en : un objet `UploadedFile` englobant le contenu du fichier et son nom dans un seul objet. - Valide que les données de fichier ont été liées au formulaire. Utilise aussi [`FileExtensionValidator`](/fr/4.0/ref/validators/#django.core.validators.FileExtensionValidator) pour valider que l’extension de fichier est prise en charge par Pillow. - Clés de messages d’erreur : `required`, `invalid`, `missing`, `empty`, `invalid_image` L’emploi de `ImageField` requiert que [Pillow](https://pillow.readthedocs.io/en/latest/) soit installé et gère les formats d’image que vous utilisez. Si vous obtenez une erreur d’image corrompue (`corrupt image`) lorsque vous téléversez une image, cela signifie généralement que Pillow ne prend pas en charge son format. Pour corriger cela, installez la bibliothèque correspondante et réinstallez Pillow. Lorsque vous utilisez un champ `ImageField` dans un formulaire, vous ne devez pas oublier de [lier les données de fichier au formulaire](/fr/4.0/ref/forms/api/#binding-uploaded-files). Après que le champ a été nettoyé et validé, l’objet `UploadedFile` comportera un attribut supplémentaire `image` contenant l’instance [Image](https://pillow.readthedocs.io/en/latest/reference/Image.html) de Pillow utilisée pour contrôler que le fichier est une image valide. Pillow ferme le descripteur de fichier sous-jacent après avoir vérifié l’image ; ainsi, alors que certains attributs de données non image tels que `format`, `height` et `width` sont accessibles, ce n’est pas le cas des méthodes qui accèdent aux données image sous-jacentes, telles que `getdata()` ou `getpixel()`, sauf si vous prenez la peine de réouvrir le fichier. Par exemple ``` >>> from PIL import Image >>> from django import forms >>> from django.core.files.uploadedfile import SimpleUploadedFile >>> class ImageForm(forms.Form): ... img = forms.ImageField() >>> file_data = {'img': SimpleUploadedFile('test.png', )} >>> form = ImageForm({}, file_data) # Pillow closes the underlying file descriptor. >>> form.is_valid() True >>> image_field = form.cleaned_data['img'] >>> image_field.image >>> image_field.image.width 191 >>> image_field.image.height 287 >>> image_field.image.format 'PNG' >>> image_field.image.getdata() # Raises AttributeError: 'NoneType' object has no attribute 'seek'. >>> image = Image.open(image_field) >>> image.getdata() ``` De plus, `UploadedFile.content_type` sera également mis à jour avec le type de contenu de l’image pour autant que Pillow puisse le déterminer, sinon il prend la valeur `None`. ### `IntegerField` #### `class IntegerField(**kwargs)` - Composant par défaut : [`NumberInput`](/fr/4.0/ref/forms/widgets/#django.forms.NumberInput) lorsque [`Field.localize`](#django.forms.Field.localize) vaut `False`, sinon [`TextInput`](/fr/4.0/ref/forms/widgets/#django.forms.TextInput). - Valeur vide : `None` - Est normalisé en : un nombre entier Python. - Valide que la valeur donnée est un nombre entier. Utilise [`MaxValueValidator`](/fr/4.0/ref/validators/#django.core.validators.MaxValueValidator) et [`MinValueValidator`](/fr/4.0/ref/validators/#django.core.validators.MinValueValidator) si `max_value` et `min_value` sont fournis. Les espaces de début et de fin sont permis, comme pour la fonction `int()` de Python. - Clés de messages d’erreur : `required`, `invalid`, `max_value`, `min_value` Les messages d’erreur `max_value` et `min_value` peuvent contenir `%(limit_value)s`, qui sera remplacé par la limite concernée. Accepte deux paramètres facultatifs liés à la validation : #### `max_value` #### `min_value` Ces paramètres contrôlent l’intervalle des valeurs autorisées dans ce champ. ### `JSONField` #### `class JSONField(encoder=None, decoder=None, **kwargs)` Un champ qui accepte des données codées en JSON pour un champ [`JSONField`](/fr/4.0/ref/models/fields/#django.db.models.JSONField). - Composant par défaut : [`Textarea`](/fr/4.0/ref/forms/widgets/#django.forms.Textarea) - Valeur vide : `None` - Est normalisé en : une représentation Python de la valeur JSON (habituellement une valeur `dict`, `list` ou `None`), en fonction de [`JSONField.decoder`](#django.forms.JSONField.decoder). - Valide que la valeur donnée est une structure JSON valide. - Clés de messages d’erreur : `required`, `invalid` Accepte deux paramètres facultatifs : #### `encoder` Une sous-classe de py:class:json.JSONEncoder pour sérialiser les types de données non prises en charge par le sérialiseur JSON standard (par ex. `datetime.datetime` ou [`UUID`](https://docs.python.org/3/library/uuid.html#uuid.UUID)). Par exemple, vous pouvez utiliser la classe [`DjangoJSONEncoder`](/fr/4.0/topics/serialization/#django.core.serializers.json.DjangoJSONEncoder). Contient `json.JSONEncoder` par défaut. #### `decoder` Une sous-classe de [`json.JSONDecoder`](https://docs.python.org/3/library/json.html#json.JSONDecoder) pour désérialiser l’entrée. La désérialisation pourrait devoir tenir compte de l’incertitude liée au type de la valeur d’entrée. Par exemple, vous courez le risque de renvoyer un objet `datetime` qui était en fait une chaîne qui était fortuitement au même format que celui choisi pour les objets `datetime`. Le `decoder` peut être utiliser pour valider les données entrées. Si [`json.JSONDecodeError`](https://docs.python.org/3/library/json.html#json.JSONDecodeError) est générée durant la désérialisation, une exception `ValidationError` sera produite. Contient `json.JSONDecoder` par défaut. > **Note** > > Si vous utilisez un formulaire [`ModelForm`](/fr/4.0/topics/forms/modelforms/#django.forms.ModelForm), ce sont les paramètres `encoder` et `decoder` de [`JSONField`](/fr/4.0/ref/models/fields/#django.db.models.JSONField) qui seront utilisés. > **Formulaires conviviaux** > > `JSONField` n’est pas particulièrement convivial dans la plupart des cas. Il s’agit cependant d’une manière utile de mettre en forme des données d’un composant côté client en vue de son envoi vers le serveur. ### `MultipleChoiceField` #### `class MultipleChoiceField(**kwargs)` - Composant par défaut : [`SelectMultiple`](/fr/4.0/ref/forms/widgets/#django.forms.SelectMultiple) - Valeur vide : `[]` (une liste vide) - Est normalisé en : une liste de chaînes. - Valide que chaque valeur dans la liste donnée existe dans la liste à choix. - Clés de messages d’erreur : `required`, `invalid_choice`, `invalid_list` Le message d’erreur `invalid_choice` peut contenir `%(value)s`, qui sera remplacé par le choix sélectionné. Requiert un paramètre supplémentaire obligatoire, `choices`, comme pour [`ChoiceField`](#django.forms.ChoiceField). ### `NullBooleanField` #### `class NullBooleanField(**kwargs)` - Composant par défaut : [`NullBooleanSelect`](/fr/4.0/ref/forms/widgets/#django.forms.NullBooleanSelect) - Valeur vide : `None` - Est normalisé en : une valeur Python `True`, `False` ou `None`. - Ne valide rien (c’est-à-dire qu’il n’y a jamais d’exception `ValidationError`). `NullBooleanField` peut être utilisé avec des composants tels que [`Select`](/fr/4.0/ref/forms/widgets/#django.forms.Select) ou [`RadioSelect`](/fr/4.0/ref/forms/widgets/#django.forms.RadioSelect) en indiquant les choix `choices` du composant ``` NullBooleanField( widget=Select( choices=[ ('', 'Unknown'), (True, 'Yes'), (False, 'No'), ] ) ) ``` ### `RegexField` #### `class RegexField(**kwargs)` - Composant par défaut : [`TextInput`](/fr/4.0/ref/forms/widgets/#django.forms.TextInput) - Valeur vide : ce qui a été indiqué dans `empty_value`. - Est normalisé en : une chaîne. - Utilise [`RegexValidator`](/fr/4.0/ref/validators/#django.core.validators.RegexValidator) pour valider que la valeur donnée correspond à une certaine expression régulière. - Clés de messages d’erreur : `required`, `invalid` Requiert un paramètre supplémentaire obligatoire : #### `regex` Une expression régulière exprimée sous forme de chaîne ou d’objet expression régulière compilée. Accepte également `max_length`, `min_length`, `strip` et `empty_value`, qui fonctionnent exactement comme pour [`CharField`](#django.forms.CharField). #### `strip` Contient `False` par défaut. Quand ce paramètre est activé, l’épuration des espaces initiales et finales s’effectue avant la validation par l’expression régulière. ### `SlugField` #### `class SlugField(**kwargs)` - Composant par défaut : [`TextInput`](/fr/4.0/ref/forms/widgets/#django.forms.TextInput) - Valeur vide : ce qui a été indiqué dans [`empty_value`](#django.forms.SlugField.empty_value). - Est normalisé en : une chaîne. - Utilise [`validate_slug`](/fr/4.0/ref/validators/#django.core.validators.validate_slug) ou [`validate_unicode_slug`](/fr/4.0/ref/validators/#django.core.validators.validate_unicode_slug) pour valider que la valeur donnée ne contient que des lettres, des nombres, des soulignements et des tirets. - Clés de messages d’erreur : `required`, `invalid` Ce champ est prévu pour l’affichage des champs de modèle [`SlugField`](/fr/4.0/ref/models/fields/#django.db.models.SlugField) dans les formulaires. Accepte deux paramètres facultatifs : #### `allow_unicode` Une valeur booléenne indiquant au champ d’accepter des lettres Unicode en plus des lettres ASCII de base. La valeur par défaut est `False`. #### `empty_value` La valeur à utiliser pour représenter une valeur vide. Contient une chaîne vide par défaut. ### `TimeField` #### `class TimeField(**kwargs)` - Composant par défaut : [`TimeInput`](/fr/4.0/ref/forms/widgets/#django.forms.TimeInput) - Valeur vide : `None` - Est normalisé en : un objet Python `datetime.time`. - Valide que la valeur donnée est un objet `datetime.time` ou une chaîne mise en forme dans un format d’heure particulier. - Clés de messages d’erreur : `required`, `invalid` Accepte un paramètre facultatif : #### `input_formats` Une liste de chaînes de format utilisées pour essayer de convertir une chaîne en un objet `datetime.time` valide. Si aucun paramètre `input_formats` n’est indiqué, les formats d’entrée par défaut sont lus dans dans [`TIME_INPUT_FORMATS`](/fr/4.0/ref/settings/#std-setting-TIME_INPUT_FORMATS) si [`USE_L10N`](/fr/4.0/ref/settings/#std-setting-USE_L10N) est `False`, ou dans la clé `TIME_INPUT_FORMATS` de la langue active si la régionalisation est activée. Voir aussi la [régionalisation des formats](/fr/4.0/topics/i18n/formatting/). ### `TypedChoiceField` #### `class TypedChoiceField(**kwargs)` Similaire à [`ChoiceField`](#django.forms.ChoiceField), sauf que [`TypedChoiceField`](#django.forms.TypedChoiceField) accepte deux paramètres supplémentaires, [`coerce`](#django.forms.TypedChoiceField.coerce) et [`empty_value`](#django.forms.TypedChoiceField.empty_value). - Composant par défaut : [`Select`](/fr/4.0/ref/forms/widgets/#django.forms.Select) - Valeur vide : ce qui a été indiqué dans [`empty_value`](#django.forms.TypedChoiceField.empty_value). - Est normalisé en : une valeur du type indiqué par le paramètre [`coerce`](#django.forms.TypedChoiceField.coerce). - Valide que la valeur donnée existe dans la liste à choix et qu’elle peut être transformée dans le bon type. - Clés de messages d’erreur : `required`, `invalid_choice` Accepte des paramètres supplémentaires : #### `coerce` Une fonction acceptant un paramètre et renvoyant une valeur transtypée. Comme exemple, on peut mentionner les fonctions Python `int`, `float`, `bool` et les autres types. Par défaut, il s’agit de la fonction identité. Notez que le forçage de type se produit après la validation de saisie, il est donc possible de forcer une valeur qui n’est pas présente dans `choices`. #### `empty_value` La valeur utilisée pour signifier « vide ». Par défaut, il s’agit de la chaîne vide ; `None` est une autre option assez fréquente ici. Remarquez que le type de cette valeur ne sera pas transformé par le contenu du paramètre `coerce`, il faut donc la choisir en conséquence. ### `TypedMultipleChoiceField` #### `class TypedMultipleChoiceField(**kwargs)` Similaire à [`MultipleChoiceField`](#django.forms.MultipleChoiceField), sauf que [`TypedMultipleChoiceField`](#django.forms.TypedMultipleChoiceField) accepte deux paramètres supplémentaires, `coerce` et `empty_value`. - Composant par défaut : [`SelectMultiple`](/fr/4.0/ref/forms/widgets/#django.forms.SelectMultiple) - Valeur vide : ce qui a été indiqué dans `empty_value` - Est normalisé en : une liste de valeurs du type indiqué par le paramètre `coerce`. - Valide que les valeurs données existent dans la liste à choix et qu’elles peuvent être transformées dans le bon type. - Clés de messages d’erreur : `required`, `invalid_choice` Le message d’erreur `invalid_choice` peut contenir `%(value)s`, qui sera remplacé par le choix sélectionné. Accepte deux paramètres supplémentaires, `coerce` et `empty_value`, comme pour [`TypedChoiceField`](#django.forms.TypedChoiceField). ### `URLField` #### `class URLField(**kwargs)` - Composant par défaut : [`URLInput`](/fr/4.0/ref/forms/widgets/#django.forms.URLInput) - Valeur vide : ce qui a été indiqué dans `empty_value`. - Est normalisé en : une chaîne. - Utilise [`URLValidator`](/fr/4.0/ref/validators/#django.core.validators.URLValidator) pour valider que la valeur donnée est une URL valide. - Clés de messages d’erreur : `required`, `invalid` Possède trois paramètres facultatifs `max_length`, `min_length` et `empty_value`, qui fonctionnent exactement comme pour [`CharField`](#django.forms.CharField). ### `UUIDField` #### `class UUIDField(**kwargs)` - Composant par défaut : [`TextInput`](/fr/4.0/ref/forms/widgets/#django.forms.TextInput) - Valeur vide : `None` - Est normalisé en : un objet [`UUID`](https://docs.python.org/3/library/uuid.html#uuid.UUID). - Clés de messages d’erreur : `required`, `invalid` Ce champ accepte toute chaîne dans un format accepté par le paramètre `hex` du constructeur [`UUID`](https://docs.python.org/3/library/uuid.html#uuid.UUID). ## Classes de champs `Field` intégrées plus complexes ### `ComboField` #### `class ComboField(**kwargs)` - Composant par défaut : [`TextInput`](/fr/4.0/ref/forms/widgets/#django.forms.TextInput) - Valeur vide : `''` (une chaîne vide) - Est normalisé en : une chaîne. - Valide que la valeur donnée est valide pour chacun des champs indiqués en paramètre de `ComboField`. - Clés de messages d’erreur : `required`, `invalid` Requiert un paramètre supplémentaire obligatoire : #### `fields` La liste des champs devant être utilisés pour valider la valeur du champ (dans l’ordre de leur présentation). ``` >>> from django.forms import ComboField >>> f = ComboField(fields=[CharField(max_length=20), EmailField()]) >>> f.clean('test@example.com') 'test@example.com' >>> f.clean('longemailaddress@example.com') Traceback (most recent call last): ... ValidationError: ['Ensure this value has at most 20 characters (it has 28).'] ``` ### `MultiValueField` #### `class MultiValueField(fields=(), **kwargs)` - Composant par défaut : [`TextInput`](/fr/4.0/ref/forms/widgets/#django.forms.TextInput) - Valeur vide : `''` (une chaîne vide) - Est normalisé en : le type renvoyé par la méthode `compress` de la sous-classe. - Valide que les valeurs données sont valides pour chacun des champs indiqués en paramètre de `MultiValueField`. - Clés de messages d’erreur : `required`, `invalid`, `incomplete` Agrège la logique de plusieurs champs qui produisent une seule valeur en commun. Ce champ est abstrait et doit être hérité. Au contraire des champs à valeur unique, les sous-classes de [`MultiValueField`](#django.forms.MultiValueField) ne doivent pas implémenter [`clean()`](#django.forms.Field.clean) mais plutôt [`compress()`](#django.forms.MultiValueField.compress). Requiert un paramètre supplémentaire obligatoire : #### `fields` Un tuple de champs dont les valeurs sont nettoyées puis ultérieurement combinées en une seule valeur. Chaque valeur du champ est nettoyée par le champ correspondant dans `fields` – la première valeur est nettoyée par le premier champ, la deuxième valeur par le deuxième champ, etc. Lorsque tous les champs ont été nettoyés, la liste de ces valeurs est combinée en une valeur unique par [`compress()`](#django.forms.MultiValueField.compress). Accepte aussi des paramètre facultatifs : #### `require_all_fields` La valeur par défaut est `True`, auquel cas une erreur de validation `required` est générée si aucune valeur n’est fournie pour aucun champ. Lorsque la valeur est `False`, l’attribut [`Field.required`](#django.forms.Field.required) peut être défini à `False` pour des champs individuels pour les rendre facultatifs. Si aucune valeur n’est fournie pour un champ obligatoire, une erreur de validation `incomplete` est générée. Un message d’erreur `incomplete` par défaut peut être défini dans la sous-classe de [`MultiValueField`](#django.forms.MultiValueField), ou il est possible de définir des messages différents pour chaque champ individuellement. Par exemple : ``` from django.core.validators import RegexValidator class PhoneField(MultiValueField): def __init__(self, **kwargs): # Define one message for all fields. error_messages = { 'incomplete': 'Enter a country calling code and a phone number.', } # Or define a different message for each field. fields = ( CharField( error_messages={'incomplete': 'Enter a country calling code.'}, validators=[ RegexValidator(r'^[0-9]+$', 'Enter a valid country calling code.'), ], ), CharField( error_messages={'incomplete': 'Enter a phone number.'}, validators=[RegexValidator(r'^[0-9]+$', 'Enter a valid phone number.')], ), CharField( validators=[RegexValidator(r'^[0-9]+$', 'Enter a valid extension.')], required=False, ), ) super().__init__( error_messages=error_messages, fields=fields, require_all_fields=False, **kwargs ) ``` #### `widget` Doit être une sous-classe de [`django.forms.MultiWidget`](/fr/4.0/ref/forms/widgets/#django.forms.MultiWidget). La valeur par défaut est [`TextInput`](/fr/4.0/ref/forms/widgets/#django.forms.TextInput), qui n’est probablement pas très utile dans ce cas. #### `compress(data_list)` Accepte une liste de valeurs valides et renvoie une version « compressée » de ces valeurs dans une seule valeur. Par exemple, [`SplitDateTimeField`](#django.forms.SplitDateTimeField) est une sous-classe qui combine un champ heure et un champ date en un seul objet `datetime`. Cette méthode doit être implémentée par les sous-classes. ### `SplitDateTimeField` #### `class SplitDateTimeField(**kwargs)` - Composant par défaut : [`SplitDateTimeWidget`](/fr/4.0/ref/forms/widgets/#django.forms.SplitDateTimeWidget) - Valeur vide : `None` - Est normalisé en : un objet Python `datetime.datetime`. - Valide que la valeur donnée est un objet `datetime.datetime` ou une chaîne mise en forme dans un format de date/heure particulier. - Clés de messages d’erreur : `required`, `invalid`, `invalid_date`, `invalid_time` Accepte deux paramètres facultatifs : #### `input_date_formats` Une liste de chaînes de format utilisées pour essayer de convertir une chaîne en un objet `datetime.date` valide. Si aucun paramètre `input_date_formats` n’est indiqué, ce sont les formats de saisie par défaut de [`DateField`](#django.forms.DateField) qui sont utilisés. #### `input_time_formats` Une liste de chaînes de format utilisées pour essayer de convertir une chaîne en un objet `datetime.time` valide. Si aucun paramètre `input_time_formats` n’est indiqué, ce sont les formats de saisie par défaut de [`TimeField`](#django.forms.TimeField) qui sont utilisés. ## Champs dédiés aux relations Deux champs sont disponibles pour représenter les relations entre modèles : [`ModelChoiceField`](#django.forms.ModelChoiceField) and [`ModelMultipleChoiceField`](#django.forms.ModelMultipleChoiceField). Ces deux champs exigent un seul paramètre `queryset` utilisé pour créer les choix du champ. Lors de la validation du formulaire, ces champs placent soit un objet de modèle (dans le cas de `ModelChoiceField`), soit plusieurs objets de modèle (dans le cas de `ModelMultipleChoiceField`) dans le dictionnaire `cleaned_data` du formulaire. Pour des usages plus complexes, il est possible d’indiquer `queryset=None` au moment de déclarer le champ de formulaire, puis de remplir `queryset` dans la méthode `__init__()` du formulaire : ``` class FooMultipleChoiceForm(forms.Form): foo_select = forms.ModelMultipleChoiceField(queryset=None) def __init__(self, *args, **kwargs): super().__init__(*args, **kwargs) self.fields['foo_select'].queryset = ... ``` `ModelChoiceField` et `ModelMultipleChoiceField` ont les deux un attribut `iterator` qui spécifie la classe utilisée pour itérer sur le jeu de requête lors de la génération des choix. Voir [Itération sur les choix relationnels](#iterating-relationship-choices) pour plus de détails. ### `ModelChoiceField` #### `class ModelChoiceField(**kwargs)` - Composant par défaut : [`Select`](/fr/4.0/ref/forms/widgets/#django.forms.Select) - Valeur vide : `None` - Est normalisé en : une instance de modèle. - Valide que l’identifiant donné existe dans le jeu de requête. - Clés de messages d’erreur : `required`, `invalid_choice` Le message d’erreur `invalid_choice` peut contenir `%(value)s`, qui sera remplacé par le choix sélectionné. Permet de sélectionner un seul objet de modèle, adapté à la représentation d’une clé étrangère. Notez que le composant par défaut de `ModelChoiceField` devient difficilement utilisable au fur et à mesure que le nombre de choix possibles augmente. Il n’est pas recommandé de l’utiliser lorsque le nombre d’éléments à choix dépasse 100. Un seul paramètre est obligatoire : #### `queryset` Un jeu de requête `QuerySet` d’objets de modèles constituant la source des choix possibles pour le champ et qui est utilisé aussi pour valider le choix de l’utilisateur. Il est évalué au moment du rendu du formulaire. `ModelChoiceField` accepte aussi plusieurs paramètres facultatifs : #### `empty_label` Par défaut, le composant ` ... ``` et : ``` # to_field_name provided field2 = forms.ModelChoiceField(queryset=..., to_field_name="name") ``` produirait : ```html ``` #### `blank` Lors de l’utilisation du composant [`RadioSelect`](/fr/4.0/ref/forms/widgets/#django.forms.RadioSelect), cet argument booléen facultatif détermine si un choix vide est créé. Par défaut, `blank` vaut `False`, auquel cas aucun choix vide n’est créé. `ModelChoiceField` possède également cet attribut : #### `iterator` La classe d’itération utilisée pour générer les choix du champ à partir de `queryset`. Par défaut, [`ModelChoiceIterator`](#django.forms.ModelChoiceIterator). La méthode `__str__()` du modèle sera appelée pour générer les représentations textuelles des objets à faire figurer dans les choix du champ. Pour fournir des représentations personnalisées, créez une sous-classe de `ModelChoiceField` et surchargez `label_from_instance`. Cette méthode reçoit un objet de modèle et doit renvoyer une chaîne représentative de l’objet. Par exemple : ``` from django.forms import ModelChoiceField class MyModelChoiceField(ModelChoiceField): def label_from_instance(self, obj): return "My Object #%i" % obj.id ``` > **Changed in Django 4.0** > > La prise en charge de valeurs `%(value)s` dans le message d’erreur `invalid_choice` a été ajouté. ### `ModelMultipleChoiceField` #### `class ModelMultipleChoiceField(**kwargs)` - Composant par défaut : [`SelectMultiple`](/fr/4.0/ref/forms/widgets/#django.forms.SelectMultiple) - Valeur vide : un `QuerySet` vide (`self.queryset.none()`) - Est normalisé en : un `QuerySet` d’instances de modèles. - Valide que chaque identifiant dans la liste donnée existe dans le jeu de requête. - Clés de messages d’erreur : `required`, `invalid_list`, `invalid_choice`, `invalid_pk_value` Le message d’erreur `invalid_choice` peut contenir `%(value)s` et le message `invalid_pk_value` peut contenir `%(pk)s`, qui seront substitués par les valeurs appropriées. Permet la sélection d’un ou de plusieurs objets de modèles, adapté à la représentation de relations plusieurs-à-plusieurs. Comme pour [`ModelChoiceField`](#django.forms.ModelChoiceField), vous pouvez utiliser `label_from_instance` afin de personnaliser les représentations des objets. Un seul paramètre est obligatoire : #### `queryset` Identique à [`ModelChoiceField.queryset`](#django.forms.ModelChoiceField.queryset). Accepte un paramètre facultatif : #### `to_field_name` Identique à [`ModelChoiceField.to_field_name`](#django.forms.ModelChoiceField.to_field_name). `ModelMultipleChoiceField` possède également cet attribut : #### `iterator` Identique à [`ModelChoiceField.iterator`](#django.forms.ModelChoiceField.iterator). ### Itération sur les choix relationnels Par défaut, [`ModelChoiceField`](#django.forms.ModelChoiceField) et [`ModelMultipleChoiceField`](#django.forms.ModelMultipleChoiceField) utilisent [`ModelChoiceIterator`](#django.forms.ModelChoiceIterator) pour générer leur choix de champ `choices`. Lors de son itération, `ModelChoiceIterator` produit des choix de tuples à 2 éléments contenant des instances [`ModelChoiceIteratorValue`](#django.forms.ModelChoiceIteratorValue) comme premier élément `value` dans chaque choix. `ModelChoiceIteratorValue` enveloppe la valeur du choix tout en maintenant une référence à l’instance de modèle source pouvant être utilisée par exemple dans des implémentations de composants personnalisés pour ajouter des [attributs data-\*](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/data-*) aux éléments `