MaskedDateField

Le MaskedDateField est un contrôle de saisie de texte conçu pour l'entrée structurée des dates. Il permet aux utilisateurs de saisir des dates sous forme de nombres et formate automatiquement l'entrée en fonction d'un masque défini lorsque le champ perd le focus. Le masque est une chaîne qui spécifie le format de date attendu, guidant à la fois l'entrée et l'affichage.

Ce composant prend en charge l'analyse flexible, la validation, la localisation et la restauration de valeurs. Il est particulièrement utile dans des formulaires tels que les inscriptions, les réservations et la planification, où des formats de dates cohérents et spécifiques à la région sont requis.

Vous cherchez une saisie de temps ?

Le MaskedDateField est axé uniquement sur les valeurs de date. Si vous avez besoin d'un composant similaire pour saisir et formater l'heure, consultez le MaskedTimeField à la place.

Basics

Le MaskedDateField peut être instancié avec ou sans paramètres. Vous pouvez définir une valeur initiale, une étiquette, un espace réservé et un écouteur d'événements pour les changements de valeur.

Afficher le code

Java

Mask rules

Le MaskedDateField prend en charge plusieurs formats de date utilisés dans le monde, qui varient par l'ordre du jour, du mois et de l'année. Les modèles courants incluent :

Jour/Mois/Année (utilisé dans la plupart de l'Europe)
Mois/Jour/Année (utilisé aux États-Unis)
Année/Mois/Jour (utilisé en Chine, au Japon et en Corée ; également le standard ISO : YYYY-MM-DD)

Au sein de ces formats, des variations locales incluent le choix du séparateur (par exemple, -, /, ou .), si les années sont à deux ou quatre chiffres, et si les mois ou jours à un chiffre sont complétés par des zéros devant.

Pour gérer cette diversité, le MaskedDateField utilise des indicateurs de format, chacun commençant par %, suivi d'une lettre représentant une partie spécifique de la date. Ces indicateurs définissent comment l'entrée est analysée et comment la date est affichée.

Date format indicators

Format	Description
`%Y`	Année
`%M`	Mois
`%D`	Jour

Modifiers

Les modificateurs permettent un meilleur contrôle sur la façon dont les composants de la date sont formatés :

Modificateur	Description
`z`	Remplissage par zéro
`s`	Représentation de texte courte
`l`	Représentation de texte longue
`p`	Nombre empaqueté
`d`	Décimal (format par défaut)

Ces options peuvent être combinées pour créer une grande variété de masques de date.

Date format localization

Le MaskedDateField s'adapte aux formats de date régionaux en définissant la locale appropriée. Cela garantit que les dates sont affichées et analysées d'une manière qui correspond aux attentes des utilisateurs.

Région	Format	Exemple
États-Unis	MM/JJ/AAAA	`07/04/2023`
Europe	JJ/MM/AAAA	`04/07/2023`
Standard ISO	AAAA-MM-JJ	`2023-07-04`

Pour appliquer la localisation, utilisez la méthode setLocale(). Elle accepte une java.util.Locale et ajuste automatiquement à la fois le formatage et l'analyse :

dateField.setLocale(Locale.FRANCE);

Parsing logic

Le MaskedDateField analyse l'entrée de l'utilisateur en fonction du masque de date défini. Il accepte à la fois des entrées numériques complètes et abrégées avec ou sans délimiteurs, permettant une saisie flexible tout en garantissant des dates valides. Le comportement d'analyse dépend de l'ordre de format défini par le masque (par exemple, %Mz/%Dz/%Yz pour mois/jour/année). Ce format détermine comment les séquences numériques sont interprétées.

Par exemple, supposons qu'aujourd'hui soit le 15 Septembre 2012, voici comment diverses entrées seraient interprétées :

Example parsing scenarios

Entrée	YMD (ISO)	MDY (US)	DMY (EU)
`1`	Un chiffre unique est toujours interprété comme un numéro de jour dans le mois en cours, donc ce serait le 1er Septembre 2012.	Même que YMD	Même que YMD
`12`	Deux chiffres sont toujours interprétés comme un numéro de jour dans le mois en cours, donc ce serait le 12 Septembre 2012.	Même que YMD	Même que YMD
`112`	Trois chiffres sont interprétés comme un numéro de mois à un chiffre suivi d'un numéro de jour à deux chiffres, donc ce serait le 12 Janvier 2012.	Même que YMD	Trois chiffres sont interprétés comme un numéro de jour à un chiffre suivi d'un numéro de mois à deux chiffres, donc ce serait le 1er Décembre 2012.
`1004`	Quatre chiffres sont interprétés comme MMJJ, donc ce serait le 4 Octobre 2012.	Même que YMD	Quatre chiffres sont interprétés comme JJMM, donc ce serait le 10 Avril 2012.
`020304`	Six chiffres sont interprétés comme YYMMJJ, donc ce serait le 4 Mars 2002.	Six chiffres sont interprétés comme MMJJYY, donc ce serait le 3 Février 2004.	Six chiffres sont interprétés comme JJMMYY, donc ce serait le 2 Mars 2004.
`8 chiffres`	Huit chiffres sont interprétés comme AAAAMMJJ. Par exemple, `20040612` est le 12 Juin 2004.	Huit chiffres sont interprétés comme MMJJAAAA. Par exemple, `06122004` est le 12 Juin 2004.	Huit chiffres sont interprétés comme JJMMAAAA. Par exemple, `06122004` est le 6 Décembre 2004.
`12/6`	Deux nombres séparés par un délimiteur valide sont interprétés comme MM/JJ, donc ce serait le 6 Décembre 2012. Remarque : Tous les caractères sauf les lettres et les chiffres sont considérés comme des délimiteurs valides.	Même que YMD	Deux nombres séparés par n'importe quel délimiteur sont interprétés comme JJ/MM, donc ce serait le 12 Juin 2012.
`3/4/5`	5 Avril 2012	4 Mars 2005	3 Avril 2005

Setting min/max constraints

Vous pouvez restreindre la plage de dates autorisée dans un MaskedDateField en utilisant les méthodes setMin() et setMax() :

dateField.setMin(LocalDate.of(2020, 1, 1));
dateField.setMax(LocalDate.of(2030, 12, 31));

Les deux méthodes acceptent des valeurs de type java.time.LocalDate. Les entrées en dehors de la plage définie seront considérées comme invalides.

Restoring the value

Le MaskedDateField comprend une fonctionnalité de restauration qui réinitialise la valeur du champ à un état prédéfini ou original. Cela est utile pour revenir à la saisie de l'utilisateur ou réinitialiser à une date par défaut.

dateField.setRestoreValue(LocalDate.of(2025, 1, 1));
dateField.restoreValue();

Ways to restore the value

Programmiquement, en appelant restoreValue()
Via le clavier, en appuyant sur ESC (c'est la touche de restauration par défaut à moins d'être remplacée par un écouteur d'événements)

Vous pouvez définir la valeur à restaurer avec setRestoreValue(), en transmettant une instance de LocalDate.

Afficher le code

Java

Validation patterns

Vous pouvez appliquer des règles de validation côté client en utilisant des expressions régulières avec la méthode setPattern() :

dateField.setPattern("^\\d{2}/\\d{2}/\\d{4}$");

Ce modèle garantit que seules les valeurs correspondant au format MM/JJ/AAAA (deux chiffres, barre oblique, deux chiffres, barre oblique, quatre chiffres) sont considérées comme valides.

Format d'expression régulière

Le modèle doit suivre la syntaxe d'expressions régulières de JavaScript comme documenté ici.

Remarques sur la gestion de l'entrée

Le champ tente d'analyser et de formatter les entrées de date numériques en fonction du masque actuel. Cependant, les utilisateurs peuvent toujours saisir manuellement des valeurs qui ne correspondent pas au format attendu. Si l'entrée est syntaxiquement valide mais sémantiquement incorrecte ou non analysable (par exemple 99/99/9999), elle peut passer les vérifications de modèle mais échouer à la validation logique. Vous devez toujours valider la valeur d'entrée dans votre logique d'application, même si un modèle d'expression régulière est défini, pour vous assurer que la date est à la fois correctement formatée et significative.

Date picker

Le MaskedDateField comprend un sélecteur de calendrier intégré qui permet aux utilisateurs de sélectionner une date visuellement, plutôt que de la taper. Cela améliore l'ergonomie pour les utilisateurs moins techniques ou lorsque des entrées précises sont nécessaires.

Afficher le code

Java

Accessing the picker

Vous pouvez accéder au sélecteur de date en utilisant getPicker() :

DatePicker picker = dateField.getPicker();

Show/hide the picker icon

Utilisez setIconVisible() pour afficher ou masquer l'icône de calendrier à côté du champ :

picker.setIconVisible(true); // affiche l'icône

Auto-open behavior

Vous pouvez configurer le sélecteur pour qu'il s'ouvre automatiquement lorsque l'utilisateur interagit avec le champ (par exemple, clique, appuie sur Entrée ou touche les flèches) :

picker.setAutoOpen(true);

Imposer la sélection via le sélecteur

Pour garantir que les utilisateurs ne peuvent sélectionner une date qu'en utilisant le sélecteur de calendrier (et non en la saisissant manuellement), combinez les deux réglages suivants :

dateField.getPicker().setAutoOpen(true); // Ouvre le sélecteur lors de l'interaction de l'utilisateur
dateField.setAllowCustomValue(false);    // Désactive la saisie de texte manuelle

Cette configuration garantit que toutes les entrées de date proviennent de l'interface du sélecteur, ce qui est utile lorsque vous souhaitez un contrôle strict du format et éliminer les problèmes d'analyse provenant de la saisie au clavier.

Manually open the calendar

Pour ouvrir le calendrier de manière programmatique :

picker.open();

Ou utilisez l'alias :

picker.show(); // pareil que open()

Show weeks in the calendar

Le sélecteur peut afficher en option les numéros de semaine dans la vue du calendrier :

picker.setShowWeeks(true);