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

required¶

Field.required¶

Par défaut, chaque classeField suppose qu’une valeur est obligatoire, ce qui fait que si vous ne fournissez pas de valeur (que ce soitNone ou une chaîne vide("")),clean() génère une exceptionValidationError:

>>>fromdjangoimportforms>>>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’estpas obligatoire, passezrequired=False au constructeur deField:

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

Lorsquerequired=False est défini pour un champField et que vous fournissez une valeur vide àclean(), la valeur renvoyée est une valeur videnormalisée et aucune exceptionValidationError n’est générée. PourCharField, la valeur renvoyée correspond àempty_value qui est une chaîne vide par défaut. Pour les autres classesField, il peut s’agir deNone (cela varie en fonction du champ).

Les composants des champs de formulaire obligatoires possèdent l’attribut HTMLrequired. Il est possible de désactiver cela en définissant l’attributForm.use_required_attribute àFalse. L’attributrequired 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ètrelabel permet d’indiquer une étiquette conviviale pour le champ. Cette valeur est utilisée lorsque le champField est affiché dans un formulaireForm.

Comme expliqué dans « Affichage des formulaires en HTML » ci-dessus, l’étiquette par défaut d’un champField 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émentantlabel pour deux de ses champs. Nous avons indiquéauto_id=False pour simplifier l’affichage :

>>>fromdjangoimportforms>>>classCommentForm(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)<tr><th>Your name:</th><td><input type="text" name="name" required></td></tr><tr><th>Your website:</th><td><input type="url" name="url"></td></tr><tr><th>Comment:</th><td><input type="text" name="comment" required></td></tr>

label_suffix¶

Field.label_suffix¶

Le paramètrelabel_suffix permet de surcharger l’attributlabel_suffix d’un formulaire pour un champ particulier :

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

initial¶

Field.initial¶

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

Pour indiquer des données initiales dynamiques, voir le paramètreForm.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 :

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

Vous vous demandez peut-être pourquoi on ne passe pas simplement un dictionnaire de valeurs initiales dans le paramètredata 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 :

>>>classCommentForm(forms.Form):...name=forms.CharField()...url=forms.URLField()...comment=forms.CharField()>>>default_data={'name':'Your name','url':'http://'}>>>f=CommentForm(default_data,auto_id=False)>>>print(f)<tr><th>Name:</th><td><input type="text" name="name" value="Your name" required></td></tr><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><tr><th>Comment:</th><td><ul class="errorlist"><li>This field is required.</li></ul><input type="text" name="comment" required></td></tr>

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 sontpas utilisées comme données de repli dans la validation lorsqu’une valeur de champ est manquante. Les valeurs initiales sontuniquement destinées à l’affichage initial d’un formulaire :

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

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

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

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ètrewidget permet d’indiquer une classeWidget à utiliser lors du rendu HTML de ce champ. VoirComposants de formulaires (« widgets ») pour plus d’informations.

help_text¶

Field.help_text¶

Le paramètrehelp_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 deForm (par ex.as_ul()).

Tout comme l’attributhelp_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émentanthelp_text pour deux de ses champs. Nous avons indiquéauto_id=False pour simplifier l’affichage :

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

error_messages¶

Field.error_messages¶

Le paramètreerror_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 :

>>>fromdjangoimportforms>>>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 sectionClasses de champs Field intégrées ci-dessous, chaque champField définit les clés de messages d’erreur qu’il utilise.

validators¶

Field.validators¶

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

Consultez ladocumentation des validateurs pour plus d’informations.

localize¶

Field.localize¶

Le paramètrelocalize 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 larégionalisation de la mise en forme pour plus d’informations.

disabled¶

Field.disabled¶

Le paramètre booléendisabled, lorsqu’il est défini àTrue, désactive un champ de formulaire en utilisant l’attribut HTMLdisabled 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.

has_changed()¶

Field.has_changed()¶

La méthodehas_changed() est utilisée pour déterminer si la valeur du champ a été modifiée par rapport à sa valeur initiale. RenvoieTrue ouFalse.

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

BooleanField¶

classBooleanField(**kwargs)¶

• Composant par défaut :CheckboxInput
• Valeur vide :False
• Est normalisé en : une valeur PythonTrue ouFalse.
• Valide que la valeur estTrue (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 deField 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.

CharField¶

classCharField(**kwargs)¶

• Composant par défaut :TextInput
• Valeur vide : ce qui a été indiqué dansempty_value.
• Est normalisé en : une chaîne.
• UtiliseMaxLengthValidator 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 quatre paramètres facultatifs liés à la validation :

max_length¶

min_length¶

Quand ils sont fournis, ces paramètres garantissent que la chaîne de caractères correspond au maximum ou au minimum à la longueur donnée.

strip¶

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

empty_value¶

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

ChoiceField¶

classChoiceField(**kwargs)¶

• 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’erreurinvalid_choice peut contenir%(value)s, qui sera remplacé par le choix sélectionné.

Accepte un paramètre supplémentaire :

choices¶

Soit un objectitérable de tuples à 2 valeurs à utiliser comme liste de choix pour ce champ, soit des choix d’uneé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ètrechoices d’un champ de modèle. Consultez ladocumentation 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.

TypedChoiceField¶

classTypedChoiceField(**kwargs)¶

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é dansempty_value.
• Est normalisé en : une valeur du type indiqué par le paramètrecoerce.
• 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 Pythonint,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.

DateField¶

classDateField(**kwargs)¶

• Composant par défaut :DateInput
• Valeur vide :None
• Est normalisé en : un objet Pythondatetime.date.
• Valide que la valeur donnée est un objetdatetime.date,datetime.datetime ou une chaîne mise en forme dans un format de date particulier.
• Clés de messages d’erreur :required,invalid

Accepte un paramètre facultatif :

input_formats¶

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

Si aucun paramètreinput_formats n’est indiqué, les formats d’entrée par défaut sont lus dans dansDATE_INPUT_FORMATS siUSE_L10N estFalse, ou dans la cléDATE_INPUT_FORMATS de la langue active si la régionalisation est activée. Voir aussi larégionalisation des formats.

DateTimeField¶

classDateTimeField(**kwargs)¶

• Composant par défaut :DateTimeInput
• Valeur vide :None
• Est normalisé en : un objet Pythondatetime.datetime.
• Valide que la valeur donnée est un objetdatetime.datetime,datetime.date ou une chaîne mise en forme dans un format de date/heure particulier.
• Clés de messages d’erreur :required,invalid

Accepte un paramètre facultatif :

input_formats¶

Une liste de chaînes de format utilisées pour essayer de convertir une chaîne en un objetdatetime.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 parparse_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ètreinput_formats n’est indiqué, les formats d’entrée par défaut sont lus dans dansDATETIME_INPUT_FORMATS etDATE_INPUT_FORMATS siUSE_L10N estFalse, ou dans les clésDATETIME_INPUT_FORMATS etDATE_INPUT_FORMATS de la langue active si la régionalisation est activée. Voir aussi larégionalisation des formats.

Changed in Django 3.1:

La prise en charge des formats de date ISO 8601 (y compris un éventuel fuseau horaire) a été ajoutée.

Le recours àDATE_INPUT_FORMATS si nécessaire dans la valeurinput_formats par défaut a été ajouté.

DecimalField¶

classDecimalField(**kwargs)¶

• Composant par défaut :NumberInput lorsqueField.localize vautFalse, sinonTextInput.
• Valeur vide :None
• Est normalisé en : un objet Pythondecimal.
• Valide que la valeur donnée est un nombre décimal. UtiliseMaxValueValidator etMinValueValidator simax_value etmin_value sont fournis. Les espaces de début et de fin sont ignorés.
• Clés de messages d’erreur :required,invalid,max_value,min_value,max_digits,max_decimal_places,max_whole_digits

Les messages d’erreurmax_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 quatre paramètres facultatifs :

max_value¶

min_value¶

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

max_digits¶

Le nombre maximum de chiffres autorisés dans la valeur (avant et après le point décimal, sans tenir compte des zéros initiaux).

decimal_places¶

Le nombre maximal de décimales autorisées.

DurationField¶

classDurationField(**kwargs)¶

• Composant par défaut :TextInput
• Valeur vide :None
• Est normalisé en : un objet Pythontimedelta.
• Valide que la valeur donnée est une chaîne qui peut être convertie en une différence de tempstimedelta. La valeur doit être comprise entredatetime.timedelta.min etdatetime.timedelta.max.
• Clés de messages d’erreur :required,invalid,overflow.

Accepte tout format queparse_duration() peut analyser.

EmailField¶

classEmailField(**kwargs)¶

• Composant par défaut :EmailInput
• Valeur vide : ce qui a été indiqué dansempty_value.
• Est normalisé en : une chaîne.
• UtiliseEmailValidator pour valider que la valeur donnée est une adresse de courriel valide, en utilisant une expression régulière moyennement complexe.
• Clés de messages d’erreur :required,invalid

Possède trois paramètres facultatifsmax_length,min_length etempty_value, qui fonctionnent exactement comme pourCharField.

FileField¶

classFileField(**kwargs)¶

• Composant par défaut :ClearableFileInput
• Valeur vide :None
• Est normalisé en : un objetUploadedFile englobant le contenu du fichier et son nom dans un seul objet.
• Peut valider que des données de fichier non vides ont été fournies au formulaire.
• Clés de messages d’erreur :required,invalid,missing,empty,max_length

Accepte deux paramètres facultatifs pour la validation,max_length 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’objetUploadedFile, consultez ladocumentation sur les envois de fichiers.

Lorsque vous utilisez un champFileField dans un formulaire, vous ne devez pas oublier delier les données de fichier au formulaire.

L’erreurmax_length porte sur la longueur du nom de fichier. Dans le message d’erreur de cette clé,%(max)d sera remplacé par la longueur maximale du nom de fichier et%(length)d sera remplacé par la longueur effective du nom de fichier.

FilePathField¶

classFilePathField(**kwargs)¶

• 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 ; seulpath 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¶

SiFalse (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. VautTrue 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. VautTrue 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.

FloatField¶

classFloatField(**kwargs)¶

• 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. UtiliseMaxValueValidator etMinValueValidator simax_value etmin_value sont fournis. 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

Accepte deux paramètres facultatifs pour la validation,max_value etmin_value. Ces paramètres contrôlent l’intervalle des valeurs autorisées dans ce champ.

ImageField¶

classImageField(**kwargs)¶

• Composant par défaut :ClearableFileInput
• Valeur vide :None
• Est normalisé en : un objetUploadedFile 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 aussiFileExtensionValidator 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 deImageField requiert quePillow soit installé et gère les formats d’image que vous utilisez. Si vous obtenez une erreur d’image corrompue (corruptimage) 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 champImageField dans un formulaire, vous ne devez pas oublier delier les données de fichier au formulaire.

Après que le champ a été nettoyé et validé, l’objetUploadedFile comportera un attribut supplémentaireimage contenant l’instanceImage 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

>>>fromPILimportImage>>>fromdjangoimportforms>>>fromdjango.core.files.uploadedfileimportSimpleUploadedFile>>>classImageForm(forms.Form):...img=forms.ImageField()>>>file_data={'img':SimpleUploadedFile('test.png',<filedata>)}>>>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.width191>>>image_field.image.height287>>>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.

IntegerField¶

classIntegerField(**kwargs)¶

• 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. UtiliseMaxValueValidator etMinValueValidator simax_value etmin_value sont fournis. 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

Les messages d’erreurmax_value etmin_value peuvent contenir%(limit_value)s, qui sera remplacé par la limite concernée.

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

max_value¶

min_value¶

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

JSONField¶

classJSONField(encoder=None,decoder=None,**kwargs)¶

New in Django 3.1.

Un champ qui accepte des données codées en JSON pour un champJSONField.

• Composant par défaut :Textarea
• Valeur vide :None
• Est normalisé en : une représentation Python de la valeur JSON (habituellement une valeurdict,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.

Contientjson.JSONEncoder par défaut.

decoder¶

Une sous-classe dejson.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.

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

Contientjson.JSONDecoder par défaut.

Note

Si vous utilisez un formulaireModelForm, 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.

GenericIPAddressField¶

classGenericIPAddressField(**kwargs)¶

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

MultipleChoiceField¶

classMultipleChoiceField(**kwargs)¶

• 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’erreurinvalid_choice peut contenir%(value)s, qui sera remplacé par le choix sélectionné.

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

TypedMultipleChoiceField¶

classTypedMultipleChoiceField(**kwargs)¶

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é dansempty_value
• Est normalisé en : une liste de valeurs du type indiqué par le paramètrecoerce.
• 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’erreurinvalid_choice peut contenir%(value)s, qui sera remplacé par le choix sélectionné.

Accepte deux paramètres supplémentaires,coerce etempty_value, comme pourTypedChoiceField.

NullBooleanField¶

classNullBooleanField(**kwargs)¶

• Composant par défaut :NullBooleanSelect
• Valeur vide :None
• Est normalisé en : une valeur PythonTrue,False ouNone.
• Ne valide rien (c’est-à-dire qu’il n’y a jamais d’exceptionValidationError).

NullBooleanField peut être utilisé avec des composants tels queSelect ouRadioSelect en indiquant les choixchoices du composant

NullBooleanField(widget=Select(choices=[('','Unknown'),(True,'Yes'),(False,'No'),]))

RegexField¶

classRegexField(**kwargs)¶

• Composant par défaut :TextInput
• Valeur vide : ce qui a été indiqué dansempty_value.
• Est normalisé en : une chaîne.
• UtiliseRegexValidator 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 égalementmax_length,min_length,strip etempty_value, qui fonctionnent exactement comme pourCharField.

strip¶

ContientFalse par défaut. Quand ce paramètre est activé, l’épuration des espaces initiales et finales s’effectue avant la validation par l’expression régulière.

SlugField¶

classSlugField(**kwargs)¶

• Composant par défaut :TextInput
• Valeur vide : ce qui a été indiqué dansempty_value.
• Est normalisé en : une chaîne.
• Utilisevalidate_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èleSlugField 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 estFalse.

empty_value¶

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

TimeField¶

classTimeField(**kwargs)¶

• Composant par défaut :TimeInput
• Valeur vide :None
• Est normalisé en : un objet Pythondatetime.time.
• Valide que la valeur donnée est un objetdatetime.time ou une chaîne mise en forme dans un format d’heure particulier.
• Clés de messages d’erreur :required,invalid

Accepte un paramètre facultatif :

input_formats¶

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

Si aucun paramètreinput_formats n’est indiqué, les formats d’entrée par défaut sont lus dans dansTIME_INPUT_FORMATS siUSE_L10N estFalse, ou dans la cléTIME_INPUT_FORMATS de la langue active si la régionalisation est activée. Voir aussi larégionalisation des formats.

URLField¶

classURLField(**kwargs)¶

• Composant par défaut :URLInput
• Valeur vide : ce qui a été indiqué dansempty_value.
• Est normalisé en : une chaîne.
• UtiliseURLValidator pour valider que la valeur donnée est une URL valide.
• Clés de messages d’erreur :required,invalid

Possède trois paramètres facultatifsmax_length,min_length etempty_value, qui fonctionnent exactement comme pourCharField.

UUIDField¶

classUUIDField(**kwargs)¶

• Composant par défaut :TextInput
• Valeur vide :None
• Est normalisé en : un objetUUID.
• Clés de messages d’erreur :required,invalid

Ce champ accepte toute chaîne dans un format accepté par le paramètrehex du constructeurUUID.

ComboField¶

classComboField(**kwargs)¶

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

>>>fromdjango.formsimportComboField>>>f=ComboField(fields=[CharField(max_length=20),EmailField()])>>>f.clean('test@example.com')'test@example.com'>>>f.clean('longemailaddress@example.com')Traceback (most recent call last):...ValidationError:['Ensure this value has at most 20 characters (it has 28).']

MultiValueField¶

classMultiValueField(fields=(),**kwargs)¶

• Composant par défaut :TextInput
• Valeur vide :'' (une chaîne vide)
• Est normalisé en : le type renvoyé par la méthodecompress de la sous-classe.
• Valide que les valeurs données sont valides pour chacun des champs indiqués en paramètre deMultiValueField.
• 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 deMultiValueField 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 dansfields – 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 estTrue, auquel cas une erreur de validationrequired est générée si aucune valeur n’est fournie pour aucun champ.

Lorsque la valeur estFalse, 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’erreurincomplete 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 :

fromdjango.core.validatorsimportRegexValidatorclassPhoneField(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 dedjango.forms.MultiWidget. La valeur par défaut estTextInput, qui n’est probablement pas très utile dans ce cas.

compress(data_list)¶

Accepte une liste de valeurs valides et renvoie une version « compressée » de ces valeurs dans une seule valeur. Par exemple,SplitDateTimeField 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.

SplitDateTimeField¶

classSplitDateTimeField(**kwargs)¶

• Composant par défaut :SplitDateTimeWidget
• Valeur vide :None
• Est normalisé en : un objet Pythondatetime.datetime.
• Valide que la valeur donnée est un objetdatetime.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 objetdatetime.date valide.

Si aucun paramètreinput_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 objetdatetime.time valide.

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

ModelChoiceField¶

classModelChoiceField(**kwargs)¶

• 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

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 deModelChoiceField 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êteQuerySet 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 deux 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 labelfield1=forms.ModelChoiceField(queryset=...,empty_label="(Nothing)")# No empty labelfield2=forms.ModelChoiceField(queryset=...,empty_label=None)

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

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 vautNone, ce qui signifie que c’est la clé primaire de chaque objet qui est utilisée. Par exemple :

# No custom to_field_namefield1=forms.ModelChoiceField(queryset=...)

produirait :

<selectid="id_field1"name="field1"><optionvalue="obj1.pk">Object1</option><optionvalue="obj2.pk">Object2</option>...</select>

et :

# to_field_name providedfield2=forms.ModelChoiceField(queryset=...,to_field_name="name")

produirait :

<selectid="id_field2"name="field2"><optionvalue="obj1.name">Object1</option><optionvalue="obj2.name">Object2</option>...</select>

ModelChoiceField possède également cet attribut :

iterator¶

La classe d’itération utilisée pour générer les choix du champ à partir dequeryset. 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 :

fromdjango.formsimportModelChoiceFieldclassMyModelChoiceField(ModelChoiceField):deflabel_from_instance(self,obj):return"My Object #%i"%obj.id

ModelMultipleChoiceField¶

classModelMultipleChoiceField(**kwargs)¶

• Composant par défaut :SelectMultiple
• Empty value: An emptyQuerySet (self.queryset.none())
• Est normalisé en : unQuerySet 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’erreurinvalid_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 pourModelChoiceField, 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.

Itération sur les choix relationnels¶

Par défaut,ModelChoiceField etModelMultipleChoiceField utilisentModelChoiceIterator pour générer leur choix de champchoices.

Lors de son itération,ModelChoiceIterator produit des choix de tuples à 2 éléments contenant des instancesModelChoiceIteratorValue comme premier élémentvalue 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 desattributs data-* aux éléments<option>.

Par exemple, considérons les modèles suivants :

fromdjango.dbimportmodelsclassTopping(models.Model):name=models.CharField(max_length=100)price=models.DecimalField(decimal_places=2,max_digits=6)def__str__(self):returnself.nameclassPizza(models.Model):topping=models.ForeignKey(Topping,on_delete=models.CASCADE)

Vous pouvez utiliser une sous-classe de composantSelect pour inclure la valeur deTopping.price sous forme d’attribut HTMLdata-price pour chaque élément<option>:

fromdjangoimportformsclassToppingSelect(forms.Select):defcreate_option(self,name,value,label,selected,index,subindex=None,attrs=None):option=super().create_option(name,value,label,selected,index,subindex,attrs)ifvalue:option['attrs']['data-price']=value.instance.pricereturnoptionclassPizzaForm(forms.ModelForm):classMeta:model=Pizzafields=['topping']widgets={'topping':ToppingSelect}

Cela produira l’élément select pourPizza.topping ainsi :

<selectid="id_topping"name="topping"required><optionvalue=""selected>---------</option><optionvalue="1"data-price="1.50">mushrooms</option><optionvalue="2"data-price="1.25">onions</option><optionvalue="3"data-price="1.75">peppers</option><optionvalue="4"data-price="2.00">pineapple</option></select>

Pour des usages plus avancés, vous pouvez créer des sous-classes deModelChoiceIterator afin de personnaliser les choix de tuples à 2 éléments qui sont produits.