Champs de formulaires¶
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.
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
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
à 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)
<div>Your name:<input type="text" name="name" required></div>
<div>Your website:<input type="url" name="url"></div>
<div>Comment:<input type="text" name="comment" required></div>
label_suffix
¶
-
Field.
label_suffix
¶
Le paramètre label_suffix
permet de surcharger l’attribut 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)
<div><label for="id_age">Age?</label><input type="number" name="age" required id="id_age"></div>
<div><label for="id_nationality">Nationality?</label><input type="text" name="nationality" required id="id_nationality"></div>
<div><label for="id_captcha_answer">2 + 2 =</label><input type="number" name="captcha_answer" required id="id_captcha_answer"></div>
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
.
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="https://")
... comment = forms.CharField()
...
>>> f = CommentForm(auto_id=False)
>>> print(f)
<div>Name:<input type="text" name="name" value="Your name" required></div>
<div>Url:<input type="url" name="url" value="https://" required></div>
<div>Comment:<input type="text" name="comment" required></div>
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": "https://"}
>>> f = CommentForm(default_data, auto_id=False)
>>> print(f)
<div>Name:
<input type="text" name="name" value="Your name" required>
</div>
<div>Url:
<ul class="errorlist"><li>Enter a valid URL.</li></ul>
<input type="url" name="url" value="https://" required aria-invalid="true">
</div>
<div>Comment:
<ul class="errorlist"><li>This field is required.</li></ul>
<input type="text" name="comment" required aria-invalid="true">
</div>
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="https://")
... 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())
<div><label for="id_day">Day:</label><input type="text" name="day" value="2023-02-11" required id="id_day"></div>
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 ») 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
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)
<div>Subject:<div class="helptext">100 characters max.</div><input type="text" name="subject" maxlength="100" required></div>
<div>Message:<input type="text" name="message" required></div>
<div>Sender:<div class="helptext">A valid email address, please.</div><input type="email" name="sender" required></div>
<div>Cc myself:<input type="checkbox" name="cc_myself"></div>
Lorsqu’un champ possède un texte d’aide, celui-ci est associé à son composant de saisie par l’attribut HTML aria-describedby
. Si le composant est produit dans un <fieldset>
, alors aria-describedby
est ajouté à cet élément, sinon il est ajouté à l’élément <input>
du composant.
>>> from django import forms
>>> class UserForm(forms.Form):
... username = forms.CharField(max_length=255, help_text="e.g., user@example.com")
...
>>> f = UserForm()
>>> print(f)
<div>
<label for="id_username">Username:</label>
<div class="helptext" id="id_username_helptext">e.g., user@example.com</div>
<input type="text" name="username" maxlength="255" required aria-describedby="id_username_helptext" id="id_username">
</div>
Lors de l’ajout d’un attribut aria-describedby
personnalisé, prenez soin d’inclure également l’identifiant id
de l’élément help_text
(si utilisé) dans l’ordre souhaité. Pour les lecteurs d’écran, les descriptions seront lues dans leur ordre d’apparition dans aria-describedby
:
>>> class UserForm(forms.Form):
... username = forms.CharField(
... max_length=255,
... help_text="e.g., user@example.com",
... widget=forms.TextInput(
... attrs={"aria-describedby": "custom-description id_username_helptext"},
... ),
... )
...
>>> f = UserForm()
>>> print(f["username"])
<input type="text" name="username" aria-describedby="custom-description id_username_helptext" maxlength="255" id="id_username" required>
aria-describedby
a été ajouté pour associer le texte d’aide help_text
à son composant.
La prise en charge de aria-describedby
a été ajoutée pour <fieldset>
.
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 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 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 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.
template_name
¶
-
Field.
template_name
¶
L’argument template_name
permet d’utiliser un gabarit personnalisé lorsque le champ est produit avec as_field_group()
. Par défaut, cette valeur est "django/forms/field.html"
. Elle peut être adaptée pour chaque champ en surchargeant cet attribut ou plus généralement en surchargeant le gabarit par défaut, voir aussi Redéfinition des gabarits de champs intégrés.
Contrôle des données de champ modifiées¶
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()
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)[source]¶ - Composant par défaut :
CheckboxInput
- Valeur vide :
False
- Est normalisé en : une valeur Python
True
ouFalse
. - Valide que la valeur est
True
(signifiant par exemple que la case à cocher est cochée) sirequired=True
pour ce champ. - Clés de messages d’erreur :
required
Note
Comme toutes les sous-classes de
Field
héritentrequired=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 bienTrue
queFalse
(par exemple une case cochée ou non), vous devez vous rappeler de passerrequired=False
au moment de créer le champBooleanField
.- Composant par défaut :
CharField
¶
-
class
CharField
(**kwargs)[source]¶ - Composant par défaut :
TextInput
- Valeur vide : ce qui a été indiqué dans
empty_value
. - Est normalisé en : une chaîne.
- Utilise
MaxLengthValidator
etMinLengthValidator
simax_length
etmin_length
sont fournis. Sinon, toutes les entrées sont valides. - Clés de messages d’erreur :
required
,max_length
,min_length
Possède les paramètres facultatifs suivants 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.
- Composant par défaut :
ChoiceField
¶
-
class
ChoiceField
(**kwargs)[source]¶ - Composant par défaut :
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
[source]¶ Soit un object itérable de tuples à 2 valeurs à utiliser comme liste de choix pour ce champ, soit un type énumération, 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, en plus de l’évaluation au moment du rendu. Par défaut, c’est une liste vide.
Type de choix
Ce champ normalise les choix à des chaînes. Donc si des choix devraient avoir des valeurs d’autres types de données, comme des entiers ou des booléens, considérez plutôt l’utilisation de champs
TypedChoiceField
.Changed in Django 5.0:La prise en charge de correspondances (dictionnaires) et de types énumeration directement dans
choices
a été ajoutée.- Composant par défaut :
DateField
¶
-
class
DateField
(**kwargs)[source]¶ - Composant par défaut :
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
¶ Un objet itérable 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 la cléDATE_INPUT_FORMATS
du format de langue actif, ou dans le réglageDATE_INPUT_FORMATS
si la régionalisation est désactivée. Voir aussi la régionalisation des formats.- Composant par défaut :
DateTimeField
¶
-
class
DateTimeField
(**kwargs)[source]¶ - Composant par défaut :
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
¶ Un objet itérable 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()
. 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 les clésDATETIME_INPUT_FORMATS
etDATE_INPUT_FORMATS
du format de langue actif, ou dans les réglagesDATETIME_INPUT_FORMATS
etDATE_INPUT_FORMATS
si la régionalisation est désactivée. Voir aussi la régionalisation des formats.- Composant par défaut :
DecimalField
¶
-
class
DecimalField
(**kwargs)[source]¶ - Composant par défaut :
NumberInput
lorsqueField.localize
vautFalse
, sinonTextInput
. - Valeur vide :
None
- Est normalisé en : un objet Python
decimal
. - Valide que la valeur donnée est un nombre décimal. Utilise
MaxValueValidator
etMinValueValidator
simax_value
etmin_value
sont fournis. UtiliseStepValueValidator
sistep_size
est fourni. 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
,step_size
.
Les messages d’erreur
max_value
etmin_value
peuvent contenir%(limit_value)s
, qui sera remplacé par la limite concernée. Sur le même principe, les messages d’erreurmax_digits
,max_decimal_places
etmax_whole_digits
peuvent contenir%(max)s
.Accepte cinq 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.
-
step_size
¶ Limite la validité des entrées à un multiple entier de
step_size
. Simin_value
est aussi indiquée, elle est ajoutée comme valeur de décalage pour déterminer si la taille de pas correspond.
- Composant par défaut :
DurationField
¶
-
class
DurationField
(**kwargs)[source]¶ - Composant par défaut :
TextInput
- Valeur vide :
None
- Est normalisé en : un objet Python
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 entredatetime.timedelta.min
etdatetime.timedelta.max
. - Clés de messages d’erreur :
required
,invalid
,overflow
.
Accepte tout format que
parse_duration()
peut analyser.- Composant par défaut :
EmailField
¶
-
class
EmailField
(**kwargs)[source]¶ - Composant par défaut :
EmailInput
- Valeur vide : ce qui a été indiqué dans
empty_value
. - Est normalisé en : une chaîne.
- Utilise
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 les paramètres facultatifs
max_length
,min_length
etempty_value
, qui fonctionnent exactement comme pourCharField
. Le paramètremax_length
contient par défaut 320 (voir RFC 3696#section-3).- Composant par défaut :
FileField
¶
-
class
FileField
(**kwargs)[source]¶ - Composant par défaut :
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 les paramètres facultatifs pour la validation,
max_length
etallow_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.Lorsque vous utilisez un champ
FileField
dans un formulaire, vous ne devez pas oublier de lier les données de fichier au formulaire.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.- Composant par défaut :
FilePathField
¶
-
class
FilePathField
(**kwargs)[source]¶ - Composant par défaut :
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 depath
sera à disposition dans les choix possibles. SiTrue
, 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
ouFalse
. La valeur par défaut estTrue
. Indique si les fichiers de l’emplacement spécifié doivent être inclus. Il faut que l’une des deux valeurs, ce champ ouallow_folders
, soitTrue
.
-
allow_folders
¶ Facultatif. Vaut
True
ouFalse
. La valeur par défaut estFalse
. 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 ouallow_files
, soitTrue
.
- Composant par défaut :
FloatField
¶
-
class
FloatField
(**kwargs)[source]¶ - Composant par défaut :
NumberInput
lorsqueField.localize
vautFalse
, sinonTextInput
. - Valeur vide :
None
- Est normalisé en : un objet Python float.
- Valide que la valeur donnée est un nombre à virgule (
float
). UtiliseMaxValueValidator
etMinValueValidator
simax_value
etmin_value
sont fournis. UtiliseStepValueValidator
sistep_size
est fourni. Les espaces de début et de fin sont permis, comme pour la fonctionfloat()
de Python. - Clés de messages d’erreur :
required
,invalid
,max_value
,min_value
,step_size
.
Accepte trois paramètres facultatifs :
-
max_value
¶
-
min_value
¶ Ces paramètres contrôlent l’intervalle des valeurs autorisées dans ce champ.
-
step_size
¶ Limite la validité des entrées à un multiple entier de
step_size
. Simin_value
est aussi indiquée, elle est ajoutée comme valeur de décalage pour déterminer si la taille de pas correspond.
- Composant par défaut :
GenericIPAddressField
¶
-
class
GenericIPAddressField
(**kwargs)[source]¶ Un champ contenant soit une adresse IPv4, soit une adresse IPv6.
- Composant par défaut :
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, 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é en2001::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 en192.0.2.1
. L’option est désactivée par défaut. Utilisable uniquement quandprotocol
est défini à'both'
.
- Composant par défaut :
ImageField
¶
-
class
ImageField
(**kwargs)[source]¶ - Composant par défaut :
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
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 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.Après que le champ a été nettoyé et validé, l’objet
UploadedFile
comportera un attribut supplémentaireimage
contenant l’instance Image 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 queformat
,height
etwidth
sont accessibles, ce n’est pas le cas des méthodes qui accèdent aux données image sous-jacentes, telles quegetdata()
ougetpixel()
, 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", b"file data")} >>> form = ImageForm({}, file_data) # Pillow closes the underlying file descriptor. >>> form.is_valid() True >>> image_field = form.cleaned_data["img"] >>> image_field.image <PIL.PngImagePlugin.PngImageFile image mode=RGBA size=191x287 at 0x7F5985045C18> >>> 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() <ImagingCore object at 0x7f5984f874b0>
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 valeurNone
.- Composant par défaut :
IntegerField
¶
-
class
IntegerField
(**kwargs)[source]¶ - Composant par défaut :
NumberInput
lorsqueField.localize
vautFalse
, sinonTextInput
. - Valeur vide :
None
- Est normalisé en : un nombre entier Python.
- Valide que la valeur donnée est un nombre entier. Utilise
MaxValueValidator
etMinValueValidator
simax_value
etmin_value
sont fournis. UtiliseStepValueValidator
sistep_size
est fourni. Les espaces de début et de fin sont permis, comme pour la fonctionint()
de Python. - Clés de messages d’erreur :
required
,invalid
,max_value
,min_value
,step_size
Les messages d’erreur
max_value
,min_value
etstep_size
peuvent contenir%(limit_value)s
, qui sera remplacé par la limite concernée.Accepte trois 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.
-
step_size
¶ Limite la validité des entrées à un multiple entier de
step_size
. Simin_value
est aussi indiquée, elle est ajoutée comme valeur de décalage pour déterminer si la taille de pas correspond.
- Composant par défaut :
JSONField
¶
-
class
JSONField
(encoder=None, decoder=None, **kwargs)[source]¶ Un champ qui accepte des données codées en JSON pour un champ
JSONField
.- Composant par défaut :
Textarea
- Valeur vide :
None
- Est normalisé en : une représentation Python de la valeur JSON (habituellement une valeur
dict
,list
ouNone
), en fonction deJSONField.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
ouUUID
). Par exemple, vous pouvez utiliser la classeDjangoJSONEncoder
.Contient
json.JSONEncoder
par défaut.
-
decoder
¶ Une sous-classe de
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 objetdatetime
qui était en fait une chaîne qui était fortuitement au même format que celui choisi pour les objetsdatetime
.Le
decoder
peut être utiliser pour valider les données entrées. Sijson.JSONDecodeError
est générée durant la désérialisation, une exceptionValidationError
sera produite.Contient
json.JSONDecoder
par défaut.
Note
Si vous utilisez un formulaire
ModelForm
, ce sont les paramètresencoder
etdecoder
deJSONField
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.- Composant par défaut :
MultipleChoiceField
¶
-
class
MultipleChoiceField
(**kwargs)[source]¶ - Composant par défaut :
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 pourChoiceField
.- Composant par défaut :
NullBooleanField
¶
-
class
NullBooleanField
(**kwargs)[source]¶ - Composant par défaut :
NullBooleanSelect
- Valeur vide :
None
- Est normalisé en : une valeur Python
True
,False
ouNone
. - Ne valide rien (c’est-à-dire qu’il n’y a jamais d’exception
ValidationError
).
NullBooleanField
peut être utilisé avec des composants tels queSelect
ouRadioSelect
en indiquant les choixchoices
du composantNullBooleanField( widget=Select( choices=[ ("", "Unknown"), (True, "Yes"), (False, "No"), ] ) )
- Composant par défaut :
RegexField
¶
-
class
RegexField
(**kwargs)[source]¶ - Composant par défaut :
TextInput
- Valeur vide : ce qui a été indiqué dans
empty_value
. - Est normalisé en : une chaîne.
- Utilise
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
etempty_value
, qui fonctionnent exactement comme pourCharField
.-
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.
- Composant par défaut :
SlugField
¶
-
class
SlugField
(**kwargs)[source]¶ - Composant par défaut :
TextInput
- Valeur vide : ce qui a été indiqué dans
empty_value
. - Est normalisé en : une chaîne.
- Utilise
validate_slug
ouvalidate_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
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.
- Composant par défaut :
TimeField
¶
-
class
TimeField
(**kwargs)[source]¶ - Composant par défaut :
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
¶ Un objet itérable 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 la cléTIME_INPUT_FORMATS
du format de langue actif, ou dans le réglageTIME_INPUT_FORMATS
si la régionalisation est désactivée. Voir aussi la régionalisation des formats.- Composant par défaut :
TypedChoiceField
¶
-
class
TypedChoiceField
(**kwargs)[source]¶ Similaire à
ChoiceField
, sauf queTypedChoiceField
accepte deux paramètres supplémentaires,coerce
etempty_value
.- Composant par défaut :
Select
- Valeur vide : ce qui a été indiqué dans
empty_value
. - Est normalisé en : une valeur du type indiqué par le paramètre
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 danschoices
.
-
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ètrecoerce
, il faut donc la choisir en conséquence.
- Composant par défaut :
TypedMultipleChoiceField
¶
-
class
TypedMultipleChoiceField
(**kwargs)[source]¶ Similaire à
MultipleChoiceField
, sauf queTypedMultipleChoiceField
accepte deux paramètres supplémentaires,coerce
etempty_value
.- Composant par défaut :
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
etempty_value
, comme pourTypedChoiceField
.- Composant par défaut :
URLField
¶
-
class
URLField
(**kwargs)[source]¶ - Composant par défaut :
URLInput
- Valeur vide : ce qui a été indiqué dans
empty_value
. - Est normalisé en : une chaîne.
- Utilise
URLValidator
pour valider que la valeur donnée est une URL valide. - Clés de messages d’erreur :
required
,invalid
Possède les paramètres facultatifs
max_length
,min_length
etempty_value
, qui fonctionnent exactement comme pourCharField
, ainsi qu’un argument supplémentaire :-
assume_scheme
¶ - New in Django 5.0.
Le protocole supposé des URL qui n’en contiennent pas. Vaut
"http"
par défaut. Par exemple, siassume_scheme
vaut"https"
et que la valeur fournie est"exemple.com"
, la valeur normalisée sera"https://exemple.com"
.
Obsolète depuis la version 5.0: La valeur par défaut de
assume_scheme
changera de"http"
à"https"
dans DJango 6.0. Définissez le réglage de transitionFORMS_URLFIELD_ASSUME_HTTPS
àTrue
pour anticiper l’usage de"https"
pendant le cycle de publication de Django 5.x.- Composant par défaut :
Classes de champs Field
intégrées plus complexes¶
ComboField
¶
-
class
ComboField
(**kwargs)[source]¶ - Composant par défaut :
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).']
- Composant par défaut :
MultiValueField
¶
-
class
MultiValueField
(fields=(), **kwargs)[source]¶ - Composant par défaut :
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
ne doivent pas implémenterclean()
mais plutôtcompress()
.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 parcompress()
.
Accepte aussi des paramètre facultatifs :
-
require_all_fields
¶ La valeur par défaut est
True
, auquel cas une erreur de validationrequired
est générée si aucune valeur n’est fournie pour aucun champ.Lorsque la valeur est
False
, l’attributField.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 validationincomplete
est générée.Un message d’erreur
incomplete
par défaut peut être défini dans la sous-classe deMultiValueField
, 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
. La valeur par défaut estTextInput
, qui n’est probablement pas très utile dans ce cas.
-
compress
(data_list)[source]¶ 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 objetdatetime
.Cette méthode doit être implémentée par les sous-classes.
- Composant par défaut :
SplitDateTimeField
¶
-
class
SplitDateTimeField
(**kwargs)[source]¶ - Composant par défaut :
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 deDateField
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 deTimeField
qui sont utilisés.- Composant par défaut :
Champs dédiés aux relations¶
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.
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 pour plus de détails.
ModelChoiceField
¶
-
class
ModelChoiceField
(**kwargs)[source]¶ - Composant par défaut :
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
<select>
utilisé parModelChoiceField
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’attributempty_label
, ou même désactiver complètement le choix vide en définissantempty_label
àNone
:# A custom empty label field1 = forms.ModelChoiceField(queryset=..., empty_label="(Nothing)") # No empty label field2 = forms.ModelChoiceField(queryset=..., empty_label=None)
Notez qu’aucun choix vide n’est créé (quelle que soit la valeur de
empty_label
) si un champModelChoiceField
est obligatoire et possède une valeur initiale par défaut, ou que son composantwidget
est class:~django.forms.RadioSelect et que son argumentblank
estFalse
.
-
to_field_name
¶ 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 :# No custom to_field_name field1 = forms.ModelChoiceField(queryset=...)
produirait :
<select id="id_field1" name="field1"> <option value="obj1.pk">Object1</option> <option value="obj2.pk">Object2</option> ... </select>
et :
# to_field_name provided field2 = forms.ModelChoiceField(queryset=..., to_field_name="name")
produirait :
<select id="id_field2" name="field2"> <option value="obj1.name">Object1</option> <option value="obj2.name">Object2</option> ... </select>
-
blank
¶ Lors de l’utilisation du composant
RadioSelect
, cet argument booléen facultatif détermine si un choix vide est créé. Par défaut,blank
vautFalse
, 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
.
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 deModelChoiceField
et surchargezlabel_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
- Composant par défaut :
ModelMultipleChoiceField
¶
-
class
ModelMultipleChoiceField
(**kwargs)[source]¶ - Composant par défaut :
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 messageinvalid_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
, vous pouvez utiliserlabel_from_instance
afin de personnaliser les représentations des objets.Un seul paramètre est obligatoire :
-
queryset
¶ Identique à
ModelChoiceField.queryset
.
Accepte un paramètre facultatif :
-
to_field_name
¶ Identique à
ModelChoiceField.to_field_name
.
ModelMultipleChoiceField
possède également cet attribut :-
iterator
¶ Identique à
ModelChoiceField.iterator
.
- Composant par défaut :
Itération sur les choix relationnels¶
Par défaut, ModelChoiceField
et ModelMultipleChoiceField
utilisent 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
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-* aux éléments <option>
.
Par exemple, considérons les modèles suivants :
from django.db import models
class Topping(models.Model):
name = models.CharField(max_length=100)
price = models.DecimalField(decimal_places=2, max_digits=6)
def __str__(self):
return self.name
class Pizza(models.Model):
topping = models.ForeignKey(Topping, on_delete=models.CASCADE)
Vous pouvez utiliser une sous-classe de composant Select
pour inclure la valeur de Topping.price
sous forme d’attribut HTML data-price
pour chaque élément <option>
:
from django import forms
class ToppingSelect(forms.Select):
def create_option(
self, name, value, label, selected, index, subindex=None, attrs=None
):
option = super().create_option(
name, value, label, selected, index, subindex, attrs
)
if value:
option["attrs"]["data-price"] = value.instance.price
return option
class PizzaForm(forms.ModelForm):
class Meta:
model = Pizza
fields = ["topping"]
widgets = {"topping": ToppingSelect}
Cela produira l’élément select pour Pizza.topping
ainsi :
<select id="id_topping" name="topping" required>
<option value="" selected>---------</option>
<option value="1" data-price="1.50">mushrooms</option>
<option value="2" data-price="1.25">onions</option>
<option value="3" data-price="1.75">peppers</option>
<option value="4" data-price="2.00">pineapple</option>
</select>
Pour des usages plus avancés, vous pouvez créer des sous-classes de ModelChoiceIterator
afin de personnaliser les choix de tuples à 2 éléments qui sont produits.
ModelChoiceIterator
¶
-
class
ModelChoiceIterator
(field)[source]¶ La classes par défaut attribuée à l’attribut
iterator
des champsModelChoiceField
etModelMultipleChoiceField
. Un objet itérable produisant des choix de tuples à 2 éléments à partir du jeu de requête.Un seul paramètre est obligatoire :
-
field
¶ L’instance
ModelChoiceField
ouModelMultipleChoiceField
sur laquelle itérer et qui produira les choix.
ModelChoiceIterator
possède la méthode suivante :-
__iter__
()[source]¶ Produit des choix de tuples à 2 éléments, au format
(value, label)
utilisé parChoiceField.choices
. Le premier élémentvalue
est une instanceModelChoiceIteratorValue
.
-
ModelChoiceIteratorValue
¶
-
class
ModelChoiceIteratorValue
(value, instance)[source]¶ Deux paramètres sont obligatoires :
-
value
¶ La valeur du choix. Cette valeur est utilisée pour produire l’attribut
value
d’un élément HTML<option>
.
-
instance
¶ L’instance de modèle provenant du jeu de requête. On peut accéder à cette instance dans des implémentations personnalisées de
ChoiceWidget.create_option()
pour ajuster le code HTML produit.
ModelChoiceIteratorValue
possède la méthode suivante :-
Création de champs personnalisés¶
Si les classes Field
intégrées ne correspondent pas à vos besoins, vous pouvez créer des classes Field
personnalisées. Pour cela, créez 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
).
Il est aussi possible de personnaliser la manière dont un champ est accédé en surchargeant get_bound_field()
.