{"title":"Champs de formulaires","version":"2.1","locale":"fr","docname":"ref/forms/fields","url":"/fr/2.1/ref/forms/fields/","canonical":"https://djangodocs.dev/fr/2.1/ref/forms/fields/","summary":"class Field ( ** kwargs ) Lien vers cette définition # Lorsque vous créez une classe Form , la partie la plus importante est de définir les champs du formulaire.…","html":"

Champs de formulairesLien vers cette rubrique#

\n
\n
\nclass Field(**kwargs)Lien vers cette définition#
\n
\n\n

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.

\n
\n
\nField.clean(value)Lien vers cette définition#
\n
\n\n

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.forms.ValidationError:

\n
Code
>>> from django import forms\n>>> f = forms.EmailField()\n>>> f.clean('foo@example.com')\n'foo@example.com'\n>>> f.clean('invalid email address')\nTraceback (most recent call last):\n...\nValidationError: ['Enter a valid email address.']\n
\n
\n

Paramètres principaux des champsLien vers cette rubrique#

\n

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 :

\n
\n

requiredLien vers cette rubrique#

\n
\n
\nField.requiredLien vers cette définition#
\n
\n\n

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:

\n
Code
>>> from django import forms\n>>> f = forms.CharField()\n>>> f.clean('foo')\n'foo'\n>>> f.clean('')\nTraceback (most recent call last):\n...\nValidationError: ['This field is required.']\n>>> f.clean(None)\nTraceback (most recent call last):\n...\nValidationError: ['This field is required.']\n>>> f.clean(' ')\n' '\n>>> f.clean(0)\n'0'\n>>> f.clean(True)\n'True'\n>>> f.clean(False)\n'False'\n
\n

Pour indiquer qu’un champ n’est pas obligatoire, passez required=False au constructeur de Field:

\n
Code
>>> f = forms.CharField(required=False)\n>>> f.clean('foo')\n'foo'\n>>> f.clean('')\n''\n>>> f.clean(None)\n''\n>>> f.clean(0)\n'0'\n>>> f.clean(True)\n'True'\n>>> f.clean(False)\n'False'\n
\n

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, il s’agit d’une chaîne vide. Pour les autres classes Field, il peut s’agir de None (cela varie en fonction du champ).

\n

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

\n
\n
\n

labelLien vers cette rubrique#

\n
\n
\nField.labelLien vers cette définition#
\n
\n\n

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.

\n

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.

\n

Voici un exemple complet de formulaire implémentant label pour deux de ses champs. Nous avons indiqué auto_id=False pour simplifier l’affichage :

\n
Code
>>> from django import forms\n>>> class CommentForm(forms.Form):\n...     name = forms.CharField(label='Your name')\n...     url = forms.URLField(label='Your website', required=False)\n...     comment = forms.CharField()\n>>> f = CommentForm(auto_id=False)\n>>> print(f)\n<tr><th>Your name:</th><td><input type="text" name="name" required></td></tr>\n<tr><th>Your website:</th><td><input type="url" name="url"></td></tr>\n<tr><th>Comment:</th><td><input type="text" name="comment" required></td></tr>\n
\n
\n
\n

label_suffixLien vers cette rubrique#

\n
\n
\nField.label_suffixLien vers cette définition#
\n
\n\n

Le paramètre label_suffix permet de surcharger l’attribut label_suffix d’un formulaire pour un champ particulier :

\n
Code
>>> class ContactForm(forms.Form):\n...     age = forms.IntegerField()\n...     nationality = forms.CharField()\n...     captcha_answer = forms.IntegerField(label='2 + 2', label_suffix=' =')\n>>> f = ContactForm(label_suffix='?')\n>>> print(f.as_p())\n<p><label for="id_age">Age?</label> <input id="id_age" name="age" type="number" required></p>\n<p><label for="id_nationality">Nationality?</label> <input id="id_nationality" name="nationality" type="text" required></p>\n<p><label for="id_captcha_answer">2 + 2 =</label> <input id="id_captcha_answer" name="captcha_answer" type="number" required></p>\n
\n
\n
\n

initialLien vers cette rubrique#

\n
\n
\nField.initialLien vers cette définition#
\n
\n\n

Le paramètre initial permet d’indiquer la valeur initiale à utiliser lors de l’affichage HTML du champ dans un formulaire Form non lié.

\n

Pour indiquer des données initiales dynamiques, voir le paramètre Form.initial.

\n

Le cas d’utilisation typique est lorsque l’on veut afficher un formulaire vierge dans lequel un champ contient initialement une valeur. Par exemple :

\n
Code
>>> from django import forms\n>>> class CommentForm(forms.Form):\n...     name = forms.CharField(initial='Your name')\n...     url = forms.URLField(initial='http://')\n...     comment = forms.CharField()\n>>> f = CommentForm(auto_id=False)\n>>> print(f)\n<tr><th>Name:</th><td><input type="text" name="name" value="Your name" required></td></tr>\n<tr><th>Url:</th><td><input type="url" name="url" value="http://" required></td></tr>\n<tr><th>Comment:</th><td><input type="text" name="comment" required></td></tr>\n
\n

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 :

\n
Code
>>> class CommentForm(forms.Form):\n...     name = forms.CharField()\n...     url = forms.URLField()\n...     comment = forms.CharField()\n>>> default_data = {'name': 'Your name', 'url': 'http://'}\n>>> f = CommentForm(default_data, auto_id=False)\n>>> print(f)\n<tr><th>Name:</th><td><input type="text" name="name" value="Your name" required></td></tr>\n<tr><th>Url:</th><td><ul class="errorlist"><li>Enter a valid URL.</li></ul><input type="url" name="url" value="http://" required></td></tr>\n<tr><th>Comment:</th><td><ul class="errorlist"><li>This field is required.</li></ul><input type="text" name="comment" required></td></tr>\n
\n

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.

\n

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 :

\n
Code
>>> class CommentForm(forms.Form):\n...     name = forms.CharField(initial='Your name')\n...     url = forms.URLField(initial='http://')\n...     comment = forms.CharField()\n>>> data = {'name': '', 'url': '', 'comment': 'Foo'}\n>>> f = CommentForm(data)\n>>> f.is_valid()\nFalse\n# The form does *not* fall back to using the initial values.\n>>> f.errors\n{'url': ['This field is required.'], 'name': ['This field is required.']}\n
\n

Au lieu d’une constante, il est aussi possible de transmettre un objet exécutable :

\n
Code
>>> import datetime\n>>> class DateForm(forms.Form):\n...     day = forms.DateField(initial=datetime.date.today)\n>>> print(DateForm())\n<tr><th>Day:</th><td><input type="text" name="day" value="12/23/2008" required><td></tr>\n
\n

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.

\n
\n
\n

widgetLien vers cette rubrique#

\n
\n
\nField.widgetLien vers cette définition#
\n
\n\n

Le paramètre widget permet d’indiquer une classe Widget à utiliser lors du rendu HTML de ce champ. Voir Composants de formulaires (« widgets ») pour plus d’informations.

\n
\n
\n

help_textLien vers cette rubrique#

\n
\n
\nField.help_textLien vers cette définition#
\n
\n\n

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()).

\n

Tout comme l’attribut 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.

\n

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 :

\n
Code
>>> from django import forms\n>>> class HelpTextContactForm(forms.Form):\n...     subject = forms.CharField(max_length=100, help_text='100 characters max.')\n...     message = forms.CharField()\n...     sender = forms.EmailField(help_text='A valid email address, please.')\n...     cc_myself = forms.BooleanField(required=False)\n>>> f = HelpTextContactForm(auto_id=False)\n>>> print(f.as_table())\n<tr><th>Subject:</th><td><input type="text" name="subject" maxlength="100" required><br><span class="helptext">100 characters max.</span></td></tr>\n<tr><th>Message:</th><td><input type="text" name="message" required></td></tr>\n<tr><th>Sender:</th><td><input type="email" name="sender" required><br>A valid email address, please.</td></tr>\n<tr><th>Cc myself:</th><td><input type="checkbox" name="cc_myself"></td></tr>\n>>> print(f.as_ul()))\n<li>Subject: <input type="text" name="subject" maxlength="100" required> <span class="helptext">100 characters max.</span></li>\n<li>Message: <input type="text" name="message" required></li>\n<li>Sender: <input type="email" name="sender" required> A valid email address, please.</li>\n<li>Cc myself: <input type="checkbox" name="cc_myself"></li>\n>>> print(f.as_p())\n<p>Subject: <input type="text" name="subject" maxlength="100" required> <span class="helptext">100 characters max.</span></p>\n<p>Message: <input type="text" name="message" required></p>\n<p>Sender: <input type="email" name="sender" required> A valid email address, please.</p>\n<p>Cc myself: <input type="checkbox" name="cc_myself"></p>\n
\n
\n
\n

error_messagesLien vers cette rubrique#

\n
\n
\nField.error_messagesLien vers cette définition#
\n
\n\n

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 :

\n
Code
>>> from django import forms\n>>> generic = forms.CharField()\n>>> generic.clean('')\nTraceback (most recent call last):\n  ...\nValidationError: ['This field is required.']\n
\n

Et voici un message d’erreur personnalisé :

\n
Code
>>> name = forms.CharField(error_messages={'required': 'Please enter your name'})\n>>> name.clean('')\nTraceback (most recent call last):\n  ...\nValidationError: ['Please enter your name']\n
\n

Dans la section Classes de champs Field intégrées ci-dessous, chaque champ Field définit les clés de messages d’erreur qu’il utilise.

\n
\n
\n

validatorsLien vers cette rubrique#

\n
\n
\nField.validatorsLien vers cette définition#
\n
\n\n

Le paramètre validators permet de définir une liste de fonctions de validation pour le champ.

\n

Consultez la documentation des validateurs pour plus d’informations.

\n
\n
\n

localizeLien vers cette rubrique#

\n
\n
\nField.localizeLien vers cette définition#
\n
\n\n

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.

\n

Consultez la documentation sur la régionalisation de la mise en forme pour plus d’informations.

\n
\n
\n

disabledLien vers cette rubrique#

\n
\n
\nField.disabledLien vers cette définition#
\n
\n\n

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.

\n
\n
\n
\n

Contrôle des données de champ modifiéesLien vers cette rubrique#

\n
\n

has_changed()Lien vers cette rubrique#

\n
\n
\nField.has_changed()Lien vers cette définition#
\n
\n\n

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.

\n

Consultez la documentation de Form.has_changed() pour plus de détails.

\n
\n
\n
\n

Classes de champs Field intégréesLien vers cette rubrique#

\n

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.

\n

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

\n
\n

BooleanFieldLien vers cette rubrique#

\n
\n
\nclass BooleanField(**kwargs)Lien vers cette définition#
\n
    \n

  • Composant par défaut : CheckboxInput

    • \n

  • Valeur vide : False

    • \n

  • Est normalisé en : une valeur Python True ou False.

    • \n

  • Valide que la valeur est True (signifiant par exemple que la case à cocher est cochée) si required=True pour ce champ.

    • \n

  • Clés de messages d’erreur : required

    • \n
\n\n
\n\n
\n
\n

CharFieldLien vers cette rubrique#

\n
\n
\nclass CharField(**kwargs)Lien vers cette définition#
\n
    \n

  • Composant par défaut : TextInput

    • \n

  • Valeur vide : ce qui a été indiqué dans empty_value.

    • \n

  • Est normalisé en : une chaîne.

    • \n

  • Utilise MaxLengthValidator et MinLengthValidator si max_length et min_length sont fournis. Sinon, toutes les entrées sont valides.

    • \n

  • Clés de messages d’erreur : required, max_length, min_length

    • \n
\n

Possède trois paramètres facultatifs liés à la validation :

\n
\n
\nmax_lengthLien vers cette définition#
\n
\n\n
\n
\nmin_lengthLien vers cette définition#
\n
\n\n

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.

\n
\n
\nstripLien vers cette définition#
\n

Si True (valeur par défaut), la valeur sera épurée d’éventuelles espaces initiales ou finales.

\n
\n\n
\n
\nempty_valueLien vers cette définition#
\n

La valeur à utiliser pour représenter une valeur vide. Contient une chaîne vide par défaut.

\n
\n\n
\n\n
\n
\n

ChoiceFieldLien vers cette rubrique#

\n
\n
\nclass ChoiceField(**kwargs)Lien vers cette définition#
\n
    \n

  • Composant par défaut : Select

    • \n

  • Valeur vide : '' (une chaîne vide)

    • \n

  • Est normalisé en : une chaîne.

    • \n

  • Valide que la valeur donnée existe dans la liste à choix.

    • \n

  • Clés de messages d’erreur : required, invalid_choice

    • \n
\n

Le message d’erreur invalid_choice peut contenir %(value)s, qui sera remplacé par le choix sélectionné.

\n

Accepte un paramètre supplémentaire :

\n
\n
\nchoicesLien vers cette définition#
\n

Soit un object itérable (par ex. une liste ou un tuple) de tuples à 2 valeurs à utiliser comme liste de choix pour ce champ, 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 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. Par défaut, c’est une liste vide.

\n
\n\n
\n\n
\n
\n

TypedChoiceFieldLien vers cette rubrique#

\n
\n
\nclass TypedChoiceField(**kwargs)Lien vers cette définition#
\n

Similaire à ChoiceField, sauf que TypedChoiceField accepte deux paramètres supplémentaires, coerce et empty_value.

\n
    \n

  • Composant par défaut : Select

    • \n

  • Valeur vide : ce qui a été indiqué dans empty_value.

    • \n

  • Est normalisé en : une valeur du type indiqué par le paramètre coerce.

    • \n

  • Valide que la valeur donnée existe dans la liste à choix et qu’elle peut être transformée dans le bon type.

    • \n

  • Clés de messages d’erreur : required, invalid_choice

    • \n
\n

Accepte des paramètres supplémentaires :

\n
\n
\ncoerceLien vers cette définition#
\n

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.

\n
\n\n
\n
\nempty_valueLien vers cette définition#
\n

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.

\n
\n\n
\n\n
\n
\n

DateFieldLien vers cette rubrique#

\n
\n
\nclass DateField(**kwargs)Lien vers cette définition#
\n
    \n

  • Composant par défaut : DateInput

    • \n

  • Valeur vide : None

    • \n

  • Est normalisé en : un objet Python datetime.date.

    • \n

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

    • \n

  • Clés de messages d’erreur : required, invalid

    • \n
\n

Accepte un paramètre facultatif :

\n
\n
\ninput_formatsLien vers cette définition#
\n

Une liste de chaînes de format utilisées pour essayer de convertir une chaîne en un objet datetime.date valide.

\n
\n\n

Si aucun paramètre input_formats n’est indiqué, les formats de saisie par défaut sont :

\n
Code
['%Y-%m-%d',      # '2006-10-25'\n '%m/%d/%Y',      # '10/25/2006'\n '%m/%d/%y']      # '10/25/06'\n
\n

De plus, si vos réglages indiquent USE_L10N=False, les éléments suivants sont aussi inclus dans les formats de saisie par défaut :

\n
Code
['%b %d %Y',      # 'Oct 25 2006'\n '%b %d, %Y',     # 'Oct 25, 2006'\n '%d %b %Y',      # '25 Oct 2006'\n '%d %b, %Y',     # '25 Oct, 2006'\n '%B %d %Y',      # 'October 25 2006'\n '%B %d, %Y',     # 'October 25, 2006'\n '%d %B %Y',      # '25 October 2006'\n '%d %B, %Y']     # '25 October, 2006'\n
\n

Voir aussi régionalisation de la mise en forme.

\n
\n\n
\n
\n

DateTimeFieldLien vers cette rubrique#

\n
\n
\nclass DateTimeField(**kwargs)Lien vers cette définition#
\n
    \n

  • Composant par défaut : DateTimeInput

    • \n

  • Valeur vide : None

    • \n

  • Est normalisé en : un objet Python datetime.datetime.

    • \n

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

    • \n

  • Clés de messages d’erreur : required, invalid

    • \n
\n

Accepte un paramètre facultatif :

\n
\n
\ninput_formatsLien vers cette définition#
\n

Une liste de chaînes de format utilisées pour essayer de convertir une chaîne en un objet datetime.datetime valide.

\n
\n\n

Si aucun paramètre input_formats n’est indiqué, les formats de saisie par défaut sont :

\n
Code
['%Y-%m-%d %H:%M:%S',    # '2006-10-25 14:30:59'\n '%Y-%m-%d %H:%M',       # '2006-10-25 14:30'\n '%Y-%m-%d',             # '2006-10-25'\n '%m/%d/%Y %H:%M:%S',    # '10/25/2006 14:30:59'\n '%m/%d/%Y %H:%M',       # '10/25/2006 14:30'\n '%m/%d/%Y',             # '10/25/2006'\n '%m/%d/%y %H:%M:%S',    # '10/25/06 14:30:59'\n '%m/%d/%y %H:%M',       # '10/25/06 14:30'\n '%m/%d/%y']             # '10/25/06'\n
\n

Voir aussi régionalisation de la mise en forme.

\n
\n\n
\n
\n

DecimalFieldLien vers cette rubrique#

\n
\n
\nclass DecimalField(**kwargs)Lien vers cette définition#
\n
    \n

  • Composant par défaut : NumberInput lorsque Field.localize vaut False, sinon TextInput.

    • \n

  • Valeur vide : None

    • \n

  • Est normalisé en : un objet Python decimal.

    • \n

  • Valide que la valeur donnée est un nombre décimal. Utilise MaxValueValidator et MinValueValidator si max_value et min_value sont fournis. Les espaces de début et de fin sont ignorés.

    • \n

  • Clés de messages d’erreur : required, invalid, max_value, min_value, max_digits, max_decimal_places, max_whole_digits

    • \n
\n

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.

\n

Accepte quatre paramètres facultatifs :

\n
\n
\nmax_valueLien vers cette définition#
\n
\n\n
\n
\nmin_valueLien vers cette définition#
\n

Ces paramètres contrôlent les intervalles de valeurs autorisées dans le champ et doivent être exprimés en valeurs decimal.Decimal.

\n
\n\n
\n
\nmax_digitsLien vers cette définition#
\n

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

\n
\n\n
\n
\ndecimal_placesLien vers cette définition#
\n

Le nombre maximal de décimales autorisées.

\n
\n\n
\n\n
\n
\n

DurationFieldLien vers cette rubrique#

\n
\n
\nclass DurationField(**kwargs)Lien vers cette définition#
\n
    \n

  • Composant par défaut : TextInput

    • \n

  • Valeur vide : None

    • \n

  • Est normalisé en : un objet Python timedelta.

    • \n

  • 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 et datetime.timedelta.max.

    • \n

  • Clés de messages d’erreur : required, invalid, overflow.

    • \n
\n

Accepte tout format que parse_duration() peut analyser.

\n
\n\n
\n
\n

EmailFieldLien vers cette rubrique#

\n
\n
\nclass EmailField(**kwargs)Lien vers cette définition#
\n
    \n

  • Composant par défaut : EmailInput

    • \n

  • Valeur vide : '' (une chaîne vide)

    • \n

  • Est normalisé en : une chaîne.

    • \n

  • Utilise EmailValidator pour valider que la valeur donnée est une adresse de courriel valide, en utilisant une expression régulière moyennement complexe.

    • \n

  • Clés de messages d’erreur : required, invalid

    • \n
\n

Accepte deux paramètres facultatifs pour la validation, max_length et min_length. S’ils sont présents, ils garantissent que la chaîne de caractères correspond au maximum ou au minimum à la longueur donnée.

\n
\n\n
\n
\n

FileFieldLien vers cette rubrique#

\n
\n
\nclass FileField(**kwargs)Lien vers cette définition#
\n
    \n

  • Composant par défaut : ClearableFileInput

    • \n

  • Valeur vide : None

    • \n

  • Est normalisé en : un objet UploadedFile englobant le contenu du fichier et son nom dans un seul objet.

    • \n

  • Peut valider que des données de fichier non vides ont été fournies au formulaire.

    • \n

  • Clés de messages d’erreur : required, invalid, missing, empty, max_length

    • \n
\n

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.

\n

Pour en savoir plus au sujet de l’objet UploadedFile, consultez la documentation sur les envois de fichiers.

\n

Lorsque vous utilisez un champ FileField dans un formulaire, vous ne devez pas oublier de lier les données de fichier au formulaire.

\n

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.

\n
\n\n
\n
\n

FilePathFieldLien vers cette rubrique#

\n
\n
\nclass FilePathField(**kwargs)Lien vers cette définition#
\n
    \n

  • Composant par défaut : Select

    • \n

  • Valeur vide : None

    • \n

  • Est normalisé en : une chaîne.

    • \n

  • Valide que le choix sélectionné existe dans la liste à choix.

    • \n

  • Clés de messages d’erreur : required, invalid_choice

    • \n
\n

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 :

\n
\n
\npathLien vers cette définition#
\n

Le chemin absolu vers le répertoire dont le contenu doit être présent dans la liste. Ce répertoire doit exister.

\n
\n\n
\n
\nrecursiveLien vers cette définition#
\n

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.

\n
\n\n
\n
\nmatchLien vers cette définition#
\n

Un motif d’expression régulière ; seuls les fichiers dont les noms correspondent à cette expression seront disponibles dans la liste à choix.

\n
\n\n
\n
\nallow_filesLien vers cette définition#
\n

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, soit True.

\n
\n\n
\n
\nallow_foldersLien vers cette définition#
\n

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, soit True.

\n
\n\n
\n\n
\n
\n

FloatFieldLien vers cette rubrique#

\n
\n
\nclass FloatField(**kwargs)Lien vers cette définition#
\n
    \n

  • Composant par défaut : NumberInput lorsque Field.localize vaut False, sinon TextInput.

    • \n

  • Valeur vide : None

    • \n

  • Est normalisé en : un objet Python float.

    • \n

  • Valide que la valeur donnée est un nombre à virgule. Utilise MaxValueValidator et 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.

    • \n

  • Clés de messages d’erreur : required, invalid, max_value, min_value

    • \n
\n

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.

\n
\n\n
\n
\n

ImageFieldLien vers cette rubrique#

\n
\n
\nclass ImageField(**kwargs)Lien vers cette définition#
\n
    \n

  • Composant par défaut : ClearableFileInput

    • \n

  • Valeur vide : None

    • \n

  • Est normalisé en : un objet UploadedFile englobant le contenu du fichier et son nom dans un seul objet.

    • \n

  • Valide que les données de fichier ont été liées au formulaire. Utilise aussi FileExtensionValidator pour valider que l’extension de fichier est prise en charge par Pillow.

    • \n

  • Clés de messages d’erreur : required, invalid, missing, empty, invalid_image

    • \n
\n

L’emploi de ImageField requiert que Pillow 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.

\n

Lorsque vous utilisez un champ ImageField dans un formulaire, vous ne devez pas oublier de lier les données de fichier au formulaire.

\n

Après que le champ a été nettoyé et validé, l’objet UploadedFile comportera un attribut supplémentaire image contenant l’instance Image de Pillow utilisée pour contrôler que le fichier est une image valide. 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.

\n
\n\n
\n
\n

IntegerFieldLien vers cette rubrique#

\n
\n
\nclass IntegerField(**kwargs)Lien vers cette définition#
\n
    \n

  • Composant par défaut : NumberInput lorsque Field.localize vaut False, sinon TextInput.

    • \n

  • Valeur vide : None

    • \n

  • Est normalisé en : un nombre entier Python.

    • \n

  • Valide que la valeur donnée est un nombre entier. Utilise MaxValueValidator et 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.

    • \n

  • Clés de messages d’erreur : required, invalid, max_value, min_value

    • \n
\n

Les messages d’erreur max_value et min_value peuvent contenir %(limit_value)s, qui sera remplacé par la limite concernée.

\n

Accepte deux paramètres facultatifs liés à la validation :

\n
\n
\nmax_valueLien vers cette définition#
\n
\n\n
\n
\nmin_valueLien vers cette définition#
\n
\n\n

Ces paramètres contrôlent l’intervalle des valeurs autorisées dans ce champ.

\n
\n\n
\n
\n

GenericIPAddressFieldLien vers cette rubrique#

\n
\n
\nclass GenericIPAddressField(**kwargs)Lien vers cette définition#
\n

Un champ contenant soit une adresse IPv4, soit une adresse IPv6.

\n
    \n

  • Composant par défaut : TextInput

    • \n

  • Valeur vide : '' (une chaîne vide)

    • \n

  • Est normalisé en : une chaîne. Les adresses IPv6 sont normalisées selon la description ci-dessous.

    • \n

  • Valide que la valeur donnée est une adresse IP valide.

    • \n

  • Clés de messages d’erreur : required, invalid

    • \n
\n

La normalisation d’adresse IPv6 respecte la section 2.2 de la RFC 4291 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.

\n

Accepte deux paramètres facultatifs :

\n
\n
\nprotocolLien vers cette définition#
\n

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.

\n
\n\n
\n
\nunpack_ipv4Lien vers cette définition#
\n

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

\n
\n\n
\n\n
\n
\n

MultipleChoiceFieldLien vers cette rubrique#

\n
\n
\nclass MultipleChoiceField(**kwargs)Lien vers cette définition#
\n
    \n

  • Composant par défaut : SelectMultiple

    • \n

  • Valeur vide : [] (une liste vide)

    • \n

  • Est normalisé en : une liste de chaînes.

    • \n

  • Valide que chaque valeur dans la liste donnée existe dans la liste à choix.

    • \n

  • Clés de messages d’erreur : required, invalid_choice, invalid_list

    • \n
\n

Le message d’erreur invalid_choice peut contenir %(value)s, qui sera remplacé par le choix sélectionné.

\n

Requiert un paramètre supplémentaire obligatoire, choices, comme pour ChoiceField.

\n
\n\n
\n
\n

TypedMultipleChoiceFieldLien vers cette rubrique#

\n
\n
\nclass TypedMultipleChoiceField(**kwargs)Lien vers cette définition#
\n

Similaire à MultipleChoiceField, sauf que TypedMultipleChoiceField accepte deux paramètres supplémentaires, coerce et empty_value.

\n
    \n

  • Composant par défaut : SelectMultiple

    • \n

  • Valeur vide : ce qui a été indiqué dans empty_value

    • \n

  • Est normalisé en : une liste de valeurs du type indiqué par le paramètre coerce.

    • \n

  • Valide que les valeurs données existent dans la liste à choix et qu’elles peuvent être transformées dans le bon type.

    • \n

  • Clés de messages d’erreur : required, invalid_choice

    • \n
\n

Le message d’erreur invalid_choice peut contenir %(value)s, qui sera remplacé par le choix sélectionné.

\n

Accepte deux paramètres supplémentaires, coerce et empty_value, comme pour TypedChoiceField.

\n
\n\n
\n
\n

NullBooleanFieldLien vers cette rubrique#

\n
\n
\nclass NullBooleanField(**kwargs)Lien vers cette définition#
\n
    \n

  • Composant par défaut : NullBooleanSelect

    • \n

  • Valeur vide : None

    • \n

  • Est normalisé en : une valeur Python True, False ou None.

    • \n

  • Ne valide rien (c’est-à-dire qu’il n’y a jamais d’exception ValidationError).

    • \n
\n
\n\n
\n
\n

RegexFieldLien vers cette rubrique#

\n
\n
\nclass RegexField(**kwargs)Lien vers cette définition#
\n
    \n

  • Composant par défaut : TextInput

    • \n

  • Valeur vide : '' (une chaîne vide)

    • \n

  • Est normalisé en : une chaîne.

    • \n

  • Utilise RegexValidator pour valider que la valeur donnée correspond à une certaine expression régulière.

    • \n

  • Clés de messages d’erreur : required, invalid

    • \n
\n

Requiert un paramètre supplémentaire obligatoire :

\n
\n
\nregexLien vers cette définition#
\n

Une expression régulière exprimée sous forme de chaîne ou d’objet expression régulière compilée.

\n
\n\n

Accepte également max_length, min_length et strip, qui fonctionnent exactement comme pour CharField.

\n
\n
\nstripLien vers cette définition#
\n

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.

\n
\n\n
\n\n
\n
\n

SlugFieldLien vers cette rubrique#

\n
\n
\nclass SlugField(**kwargs)Lien vers cette définition#
\n
    \n

  • Composant par défaut : TextInput

    • \n

  • Valeur vide : '' (une chaîne vide)

    • \n

  • Est normalisé en : une chaîne.

    • \n

  • Utilise validate_slug ou validate_unicode_slug pour valider que la valeur donnée ne contient que des lettres, des nombres, des soulignements et des tirets.

    • \n

  • Clés de messages d’erreur : required, invalid

    • \n
\n

Ce champ est prévu pour l’affichage des champs de modèle SlugField dans les formulaires.

\n

Accepte un paramètre facultatif :

\n
\n
\nallow_unicodeLien vers cette définition#
\n

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.

\n
\n\n
\n\n
\n
\n

TimeFieldLien vers cette rubrique#

\n
\n
\nclass TimeField(**kwargs)Lien vers cette définition#
\n
    \n

  • Composant par défaut : TimeInput

    • \n

  • Valeur vide : None

    • \n

  • Est normalisé en : un objet Python datetime.time.

    • \n

  • Valide que la valeur donnée est un objet datetime.time ou une chaîne mise en forme dans un format d’heure particulier.

    • \n

  • Clés de messages d’erreur : required, invalid

    • \n
\n

Accepte un paramètre facultatif :

\n
\n
\ninput_formatsLien vers cette définition#
\n

Une liste de chaînes de format utilisées pour essayer de convertir une chaîne en un objet datetime.time valide.

\n
\n\n

Si aucun paramètre input_formats n’est indiqué, les formats de saisie par défaut sont :

\n
Code
'%H:%M:%S',     # '14:30:59'\n'%H:%M',        # '14:30'\n
\n
\n\n
\n
\n

URLFieldLien vers cette rubrique#

\n
\n
\nclass URLField(**kwargs)Lien vers cette définition#
\n
    \n

  • Composant par défaut : URLInput

    • \n

  • Valeur vide : '' (une chaîne vide)

    • \n

  • Est normalisé en : une chaîne.

    • \n

  • Utilise URLValidator pour valider que la valeur donnée est une URL valide.

    • \n

  • Clés de messages d’erreur : required, invalid

    • \n
\n

Accepte les paramètres facultatifs suivants :

\n
\n
\nmax_lengthLien vers cette définition#
\n
\n\n
\n
\nmin_lengthLien vers cette définition#
\n
\n\n

Ces paramètres sont identiques à CharField.max_length et CharField.min_length.

\n
\n\n
\n
\n

UUIDFieldLien vers cette rubrique#

\n
\n
\nclass UUIDField(**kwargs)Lien vers cette définition#
\n
    \n

  • Composant par défaut : TextInput

    • \n

  • Valeur vide : '' (une chaîne vide)

    • \n

  • Est normalisé en : un objet UUID.

    • \n

  • Clés de messages d’erreur : required, invalid

    • \n
\n

Ce champ accepte toute chaîne dans un format accepté par le paramètre hex du constructeur UUID.

\n
\n\n
\n
\n
\n

Classes de champs Field intégrées plus complexesLien vers cette rubrique#

\n
\n

ComboFieldLien vers cette rubrique#

\n
\n
\nclass ComboField(**kwargs)Lien vers cette définition#
\n
    \n

  • Composant par défaut : TextInput

    • \n

  • Valeur vide : '' (une chaîne vide)

    • \n

  • Est normalisé en : une chaîne.

    • \n

  • Valide que la valeur donnée est valide pour chacun des champs indiqués en paramètre de ComboField.

    • \n

  • Clés de messages d’erreur : required, invalid

    • \n
\n

Requiert un paramètre supplémentaire obligatoire :

\n
\n
\nfieldsLien vers cette définition#
\n

La liste des champs devant être utilisés pour valider la valeur du champ (dans l’ordre de leur présentation).

\n
Code
>>> from django.forms import ComboField\n>>> f = ComboField(fields=[CharField(max_length=20), EmailField()])\n>>> f.clean('test@example.com')\n'test@example.com'\n>>> f.clean('longemailaddress@example.com')\nTraceback (most recent call last):\n...\nValidationError: ['Ensure this value has at most 20 characters (it has 28).']\n
\n
\n\n
\n\n
\n
\n

MultiValueFieldLien vers cette rubrique#

\n
\n
\nclass MultiValueField(fields=(), **kwargs)Lien vers cette définition#
\n
    \n

  • Composant par défaut : TextInput

    • \n

  • Valeur vide : '' (une chaîne vide)

    • \n

  • Est normalisé en : le type renvoyé par la méthode compress de la sous-classe.

    • \n

  • Valide que les valeurs données sont valides pour chacun des champs indiqués en paramètre de MultiValueField.

    • \n

  • Clés de messages d’erreur : required, invalid, incomplete

    • \n
\n

Agrège la logique de plusieurs champs qui produisent une seule valeur en commun.

\n

Ce champ est abstrait et doit être hérité. Au contraire des champs à valeur unique, les sous-classes de MultiValueField ne doivent pas implémenter clean() mais plutôt compress().

\n

Requiert un paramètre supplémentaire obligatoire :

\n
\n
\nfieldsLien vers cette définition#
\n

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().

\n
\n\n

Accepte aussi des paramètre facultatifs :

\n
\n
\nrequire_all_fieldsLien vers cette définition#
\n

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.

\n

Lorsque la valeur est False, l’attribut 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.

\n

Un message d’erreur incomplete par défaut peut être défini dans la sous-classe de MultiValueField, ou il est possible de définir des messages différents pour chaque champ individuellement. Par exemple :

\n
Code
from django.core.validators import RegexValidator\n\nclass PhoneField(MultiValueField):\n    def __init__(self, **kwargs):\n        # Define one message for all fields.\n        error_messages = {\n            'incomplete': 'Enter a country calling code and a phone number.',\n        }\n        # Or define a different message for each field.\n        fields = (\n            CharField(\n                error_messages={'incomplete': 'Enter a country calling code.'},\n                validators=[\n                    RegexValidator(r'^[0-9]+$', 'Enter a valid country calling code.'),\n                ],\n            ),\n            CharField(\n                error_messages={'incomplete': 'Enter a phone number.'},\n                validators=[RegexValidator(r'^[0-9]+$', 'Enter a valid phone number.')],\n            ),\n            CharField(\n                validators=[RegexValidator(r'^[0-9]+$', 'Enter a valid extension.')],\n                required=False,\n            ),\n        )\n        super().__init__(\n            error_messages=error_messages, fields=fields,\n            require_all_fields=False, **kwargs\n        )\n
\n
\n\n
\n
\nwidgetLien vers cette définition#
\n

Doit être une sous-classe de django.forms.MultiWidget. La valeur par défaut est TextInput, qui n’est probablement pas très utile dans ce cas.

\n
\n\n
\n
\ncompress(data_list)Lien vers cette définition#
\n

Accepte une liste de valeurs valides et renvoie une version « compressée » de ces valeurs dans une seule valeur. Par exemple, SplitDateTimeField est une sous-classe qui combine un champ heure et un champ date en un seul objet datetime.

\n

Cette méthode doit être implémentée par les sous-classes.

\n
\n\n
\n\n
\n
\n

SplitDateTimeFieldLien vers cette rubrique#

\n
\n
\nclass SplitDateTimeField(**kwargs)Lien vers cette définition#
\n
    \n

  • Composant par défaut : SplitDateTimeWidget

    • \n

  • Valeur vide : None

    • \n

  • Est normalisé en : un objet Python datetime.datetime.

    • \n

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

    • \n

  • Clés de messages d’erreur : required, invalid, invalid_date, invalid_time

    • \n
\n

Accepte deux paramètres facultatifs :

\n
\n
\ninput_date_formatsLien vers cette définition#
\n

Une liste de chaînes de format utilisées pour essayer de convertir une chaîne en un objet datetime.date valide.

\n
\n\n

Si aucun paramètre input_date_formats n’est indiqué, ce sont les formats de saisie par défaut de DateField qui sont utilisés.

\n
\n
\ninput_time_formatsLien vers cette définition#
\n

Une liste de chaînes de format utilisées pour essayer de convertir une chaîne en un objet datetime.time valide.

\n
\n\n

Si aucun paramètre input_time_formats n’est indiqué, ce sont les formats de saisie par défaut de TimeField qui sont utilisés.

\n
\n\n
\n
\n
\n

Champs dédiés aux relationsLien vers cette rubrique#

\n

Deux champs sont disponibles pour représenter les relations entre modèles : ModelChoiceField and 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.

\n

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 :

\n
Code
class FooMultipleChoiceForm(forms.Form):\n    foo_select = forms.ModelMultipleChoiceField(queryset=None)\n\n    def __init__(self, *args, **kwargs):\n        super().__init__(*args, **kwargs)\n        self.fields['foo_select'].queryset = ...\n
\n
\n

ModelChoiceFieldLien vers cette rubrique#

\n
\n
\nclass ModelChoiceField(**kwargs)Lien vers cette définition#
\n
    \n

  • Composant par défaut : Select

    • \n

  • Valeur vide : None

    • \n

  • Est normalisé en : une instance de modèle.

    • \n

  • Valide que l’identifiant donné existe dans le jeu de requête.

    • \n

  • Clés de messages d’erreur : required, invalid_choice

    • \n
\n

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.

\n

Un seul paramètre est obligatoire :

\n
\n
\nquerysetLien vers cette définition#
\n

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.

\n
\n\n

ModelChoiceField accepte aussi deux paramètres facultatifs :

\n
\n
\nempty_labelLien vers cette définition#
\n

Par défaut, le composant <select> utilisé par ModelChoiceField comportera un choix vide en premier dans la liste. Vous pouvez adapter le texte de cette étiquette (qui est "---------" par défaut) au moyen de l’attribut empty_label, ou même désactiver complètement le choix vide en définissant empty_label à None:

\n
Code
# A custom empty label\nfield1 = forms.ModelChoiceField(queryset=..., empty_label="(Nothing)")\n\n# No empty label\nfield2 = forms.ModelChoiceField(queryset=..., empty_label=None)\n
\n

Notez que si un ModelChoiceField est obligatoire et qu’il contient une valeur initiale par défaut, aucun choix vide n’est créé (quelle que soit la valeur de empty_label).

\n
\n\n
\n
\nto_field_nameLien vers cette définition#
\n

Ce paramètre facultatif est utilisé pour désigner le champ à utiliser comme valeur des choix dans le composant du champ. Contrôlez qu’il s’agit bien d’un champ unique du modèle, sinon la valeur sélectionnée pourrait correspondre à plus d’un objet. Par défaut ce paramètre vaut None, ce qui signifie que c’est la clé primaire de chaque objet qui est utilisée. Par exemple :

\n
Code
# No custom to_field_name\nfield1 = forms.ModelChoiceField(queryset=...)\n
\n

produirait :

\n
Html
<select id="id_field1" name="field1">\n<option value="obj1.pk">Object1</option>\n<option value="obj2.pk">Object2</option>\n...\n</select>\n
\n

et :

\n
Code
# to_field_name provided\nfield2 = forms.ModelChoiceField(queryset=..., to_field_name="name")\n
\n

produirait :

\n
Html
<select id="id_field2" name="field2">\n<option value="obj1.name">Object1</option>\n<option value="obj2.name">Object2</option>\n...\n</select>\n
\n
\n\n

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 :

\n
Code
from django.forms import ModelChoiceField\n\nclass MyModelChoiceField(ModelChoiceField):\n    def label_from_instance(self, obj):\n        return "My Object #%i" % obj.id\n
\n
\n\n
\n
\n

ModelMultipleChoiceFieldLien vers cette rubrique#

\n
\n
\nclass ModelMultipleChoiceField(**kwargs)Lien vers cette définition#
\n
    \n

  • Composant par défaut : SelectMultiple

    • \n

  • Valeur vide : un QuerySet vide (self.queryset.none())

    • \n

  • Est normalisé en : un QuerySet d’instances de modèles.

    • \n

  • Valide que chaque identifiant dans la liste donnée existe dans le jeu de requête.

    • \n

  • Clés de messages d’erreur : required, list, invalid_choice, invalid_pk_value

    • \n
\n

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.

\n

Permet la sélection d’un ou de plusieurs objets de modèles, adapté à la représentation de relations plusieurs-à-plusieurs. Comme pour ModelChoiceField, vous pouvez utiliser label_from_instance afin de personnaliser les représentations des objets.

\n

Un seul paramètre est obligatoire :

\n
\n
\nquerysetLien vers cette définition#
\n

Identique à ModelChoiceField.queryset.

\n
\n\n

Accepte un paramètre facultatif :

\n
\n
\nto_field_nameLien vers cette définition#
\n

Identique à ModelChoiceField.to_field_name.

\n
\n\n
\n\n
\n
\n
\n

Création de champs personnalisésLien vers cette rubrique#

\n

Si les classes Field intégrées ne correspondent pas à vos besoins, vous pouvez facilement créer des classes Field personnalisées. Pour cela, il suffit de créer une sous-classe de django.forms.Field. Les seules exigences sont que la méthode clean() doit être implémentée et que la méthode __init__() accepte les paramètres de base mentionnés plus haut (required, label, initial, widget, help_text).

\n

Il est aussi possible de personnaliser la manière dont un champ est accédé en surchargeant get_bound_field().

\n
","rootId":"module-django.forms.fields","toc":[{"title":"Paramètres principaux des champs","anchor":"core-field-arguments","children":[{"title":"required","anchor":"required","children":[]},{"title":"label","anchor":"label","children":[]},{"title":"label_suffix","anchor":"label-suffix","children":[]},{"title":"initial","anchor":"initial","children":[]},{"title":"widget","anchor":"widget","children":[]},{"title":"help_text","anchor":"help-text","children":[]},{"title":"error_messages","anchor":"error-messages","children":[]},{"title":"validators","anchor":"validators","children":[]},{"title":"localize","anchor":"localize","children":[]},{"title":"disabled","anchor":"disabled","children":[]}]},{"title":"Contrôle des données de champ modifiées","anchor":"checking-if-the-field-data-has-changed","children":[{"title":"has_changed()","anchor":"has-changed","children":[]}]},{"title":"Classes de champs Field intégrées","anchor":"built-in-field-classes","children":[{"title":"BooleanField","anchor":"booleanfield","children":[]},{"title":"CharField","anchor":"charfield","children":[]},{"title":"ChoiceField","anchor":"choicefield","children":[]},{"title":"TypedChoiceField","anchor":"typedchoicefield","children":[]},{"title":"DateField","anchor":"datefield","children":[]},{"title":"DateTimeField","anchor":"datetimefield","children":[]},{"title":"DecimalField","anchor":"decimalfield","children":[]},{"title":"DurationField","anchor":"durationfield","children":[]},{"title":"EmailField","anchor":"emailfield","children":[]},{"title":"FileField","anchor":"filefield","children":[]},{"title":"FilePathField","anchor":"filepathfield","children":[]},{"title":"FloatField","anchor":"floatfield","children":[]},{"title":"ImageField","anchor":"imagefield","children":[]},{"title":"IntegerField","anchor":"integerfield","children":[]},{"title":"GenericIPAddressField","anchor":"genericipaddressfield","children":[]},{"title":"MultipleChoiceField","anchor":"multiplechoicefield","children":[]},{"title":"TypedMultipleChoiceField","anchor":"typedmultiplechoicefield","children":[]},{"title":"NullBooleanField","anchor":"nullbooleanfield","children":[]},{"title":"RegexField","anchor":"regexfield","children":[]},{"title":"SlugField","anchor":"slugfield","children":[]},{"title":"TimeField","anchor":"timefield","children":[]},{"title":"URLField","anchor":"urlfield","children":[]},{"title":"UUIDField","anchor":"uuidfield","children":[]}]},{"title":"Classes de champs Field intégrées plus complexes","anchor":"slightly-complex-built-in-field-classes","children":[{"title":"ComboField","anchor":"combofield","children":[]},{"title":"MultiValueField","anchor":"multivaluefield","children":[]},{"title":"SplitDateTimeField","anchor":"splitdatetimefield","children":[]}]},{"title":"Champs dédiés aux relations","anchor":"fields-which-handle-relationships","children":[{"title":"ModelChoiceField","anchor":"modelchoicefield","children":[]},{"title":"ModelMultipleChoiceField","anchor":"modelmultiplechoicefield","children":[]}]},{"title":"Création de champs personnalisés","anchor":"creating-custom-fields","children":[]}],"breadcrumbs":[{"docname":"ref/index","title":"Référence de l’API","url":"/fr/2.1/ref/"},{"docname":"ref/forms/index","title":"Formulaires","url":"/fr/2.1/ref/forms/"}],"prev":{"docname":"ref/forms/api","title":"L’API des formulaires","url":"/fr/2.1/ref/forms/api/"},"next":{"docname":"ref/forms/models","title":"Fonctions de formulaires de modèles","url":"/fr/2.1/ref/forms/models/"},"formats":{"html":"/fr/2.1/ref/forms/fields/","markdown":"/fr/2.1/ref/forms/fields.md","json":"/fr/2.1/ref/forms/fields.json"},"source":"https://github.com/django/django/blob/stable/2.1.x/docs/ref/forms/fields.txt","official":"https://docs.djangoproject.com/fr/2.1/ref/forms/fields/","inVersions":["6.1","6.0","5.2","5.1","5.0","4.2","4.1","4.0","3.2","3.1","3.0","2.2","2.1","2.0","1.11","1.10","1.9"],"inLocales":["en","zh-hans","fr","ja","id","pt-br","ko","es","el","pl"]}