MaskedDateField

Le MaskedDateField est un contrôle d'entrée de texte conçu pour la saisie de dates structurées. Il permet aux utilisateurs d'entrer 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 le parsing flexible, la validation, la localisation et la restauration des valeurs. Il est particulièrement utile dans des formulaires tels que les enregistrements, les réservations et la planification, où des formats de date cohérents et spécifiques à la région sont nécessaires.

Vous recherchez une entrée de temps ?

Le MaskedDateField est uniquement axé sur les valeurs de date. Si vous avez besoin d'un composant similaire pour entrer et formater des heures, 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 selon l'ordre du jour, du mois et de l'année. Les motifs communs 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 la norme ISO : YYYY-MM-DD)

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

Pour gérer cette diversité, le MaskedDateField utilise des indicateurs de format, chacun commençant par %, suivi d'une lettre qui représente 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`	Rembourrage à zéro
`s`	Représentation textuelle courte
`l`	Représentation textuelle longue
`p`	Nombre compressé
`d`	Décimal (format par défaut)

Ceux-ci peuvent être combinés pour construire 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/DD/YYYY	`07/04/2023`
Europe	DD/MM/YYYY	`04/07/2023`
Norme ISO	YYYY-MM-DD	`2023-07-04`

Pour appliquer la localisation, utilisez la méthode setLocale(). Elle accepte un 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 entrée flexible tout en garantissant des dates valides. Le comportement d'analyse dépend de l'ordre du 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 seul chiffre est toujours interprété comme un numéro de jour dans le mois en cours, donc cela 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 cela 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 à 1 chiffre suivi d'un numéro de jour à 2 chiffres, donc cela serait le 12 janvier 2012.	Même que YMD	Trois chiffres sont interprétés comme un numéro de jour à 1 chiffre suivi d'un numéro de mois à 2 chiffres, donc cela serait le 1er décembre 2012.
`1004`	Quatre chiffres sont interprétés comme MMDD, donc cela serait le 4 octobre 2012.	Même que YMD	Quatre chiffres sont interprétés comme DDMM, donc cela serait le 10 avril 2012.
`020304`	Six chiffres sont interprétés comme YYMMDD, donc cela serait le 4 mars 2002.	Six chiffres sont interprétés comme MMDDYY, donc cela serait le 3 février 2004.	Six chiffres sont interprétés comme DDMMYY, donc cela serait le 2 mars 2004.
`8 digits`	Huit chiffres sont interprétés comme YYYYMMDD. Par exemple, `20040612` est le 12 juin 2004.	Huit chiffres sont interprétés comme MMDDYYYY. Par exemple, `06122004` est le 12 juin 2004.	Huit chiffres sont interprétés comme DDMMYYYY. 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/DD, donc cela 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 un délimiteur sont interprétés comme DD/MM, donc cela serait le 12 juin 2012.
`3/4/5`	5 avril 2012	4 mars 2005	3 avril 2005

Textual date parsing 25.11

Par défaut, le MaskedDateField n'accepte que des entrées numériques pour les dates. Cependant, vous pouvez activer le parsing de date textuelle pour permettre aux utilisateurs d'entrer des noms de mois et de jours dans leur entrée. Cette fonctionnalité est particulièrement utile pour créer une saisie de date plus naturelle.

Pour activer le parsing textuel, utilisez la méthode setTextualDateParsing() :

dateField.setTextualDateParsing(true);

Month name substitution

Lorsque le parsing textuel est activé, vous pouvez utiliser des modificateurs spéciaux dans votre masque pour accepter les noms de mois plutôt que des valeurs numériques :

%Ms - Accepte les noms de mois courts (Jan, Fév, Mar, etc.)
%Ml - Accepte les noms de mois longs (Janvier, Février, Mars, etc.)

Les noms de mois peuvent apparaître à n'importe quelle position dans le masque, et le champ acceptera toujours une entrée numérique comme solution de secours.

Examples

Masque	Input	Résultat
`%Ms/%Dz/%Yz`	`Sep/01/25`	Valide - Analyse comme le 1er septembre 2025
`%Ml/%Dz/%Yz`	`Septembre/01/25`	Valide - Analyse comme le 1er septembre 2025
`%Dz/%Ml/%Yz`	`01/Septembre/25`	Valide - Analyse comme le 1er septembre 2025
`%Mz/%Dz/%Yz`	`09/01/25`	Valide - La solution numérique de secours fonctionne toujours

info

Tous les 12 mois sont supportés, à la fois en forme courte (Jan, Fév, Mar, Avr, Mai, Jun, Jul, Aoû, Sep, Oct, Nov, Déc) et en forme longue (Janvier, Février, etc.).

Day name decoration

Les noms de jour de la semaine peuvent être inclus dans l'entrée pour une meilleure lisibilité, mais ils sont uniquement décoratifs et sont retirés lors de l'analyse. Ils n'affectent pas la valeur de date réelle.

%Ds - Accepte les noms de jour courts (Lun, Mar, Mer, etc.)
%Dl - Accepte les noms de jour longs (Lundi, Mardi, Mercredi, etc.)

Les noms de jour nécessitent un jour numérique

Lors de l'utilisation des noms de jour de la semaine (%Ds ou %Dl), votre masque doit également inclure %Dz ou %Dd pour spécifier le numéro de jour réel. Sans un composant de jour numérique, l'entrée sera invalide.

Examples

Masque	Input	Résultat
`%Ds %Mz/%Dz/%Yz`	`Lun 09/01/25`	Valide - Le nom du jour est décoratif
`%Dl %Mz/%Dz/%Yz`	`Lundi 09/01/25`	Valide - Le nom du jour est décoratif
`%Mz/%Dz/%Yz %Ds`	`09/01/25 Mar`	Valide - Le nom du jour à la fin
`%Dl/%Mz/%Yz`	`Lundi/09/25`	Invalide - `%Dz` manquant
`%Mz/%Dl/%Yz`	`09/Lundi/25`	Invalide - `%Dz` manquant

Tous les 7 jours de la semaine sont supportés en forme courte (Lun, Mar, Mer, Jeu, Ven, Sam, Dim) et en forme longue (Lundi, Mardi, etc.).

Additional parsing rules

Le parsing textuel de date comprend plusieurs fonctionnalités utiles :

Insensible à la casse : Des entrées comme LUNDI 09/01/25, lundi 09/01/25 ou Lundi 09/01/25 fonctionnent toutes de la même manière.
Sensible à la locale : Les noms des mois et des jours doivent correspondre à la locale configurée du champ. Par exemple, avec une locale française, utilisez septembre et non September. Les noms anglais ne seront pas reconnus à moins que la locale soit définie sur l'anglais.
- Locale française : septembre/01/25 est reconnu comme septembre.
- Locale allemande : Montag 09/01/25 est reconnu avec lundi comme nom du jour.

Setting min/max constraints

Vous pouvez restreindre la plage de dates autorisées 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 à l'entrée 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

Programmé, 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 passant une instance LocalDate.

Afficher le code

Java

Validation patterns

Vous pouvez appliquer des règles de validation côté client à l'aide d'expressions régulières avec la méthode setPattern() :

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

Ce motif garantit que seuls les valeurs correspondant au format MM/DD/YYYY (deux chiffres, barre oblique, deux chiffres, barre oblique, quatre chiffres) sont considérées comme valides.

Format d'expressions régulières

Le motif doit suivre la syntaxe des RegExp de JavaScript comme documenté ici.

Remarques sur la gestion des entrées

Le champ essaie d'analyser et de formater les entrées numériques de date en fonction du masque actuel. Cependant, les utilisateurs peuvent toujours entrer manuellement des valeurs qui ne correspondent pas au format attendu. Si l'entrée est syntaxiquement valide mais sémantiquement incorrecte ou impossible à analyser (par exemple, 99/99/9999), elle peut passer les vérifications de motif mais échouer à la validation logique. Vous devez toujours valider la valeur d'entrée dans la logique de votre application, même si un motif d'expression régulière est défini, pour garantir 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'utilité 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 sur les touches fléchées) :

picker.setAutoOpen(true);

Imposer la sélection via le sélecteur

Pour garantir que les utilisateurs ne peuvent sélectionner une date qu'à l'aide du sélecteur de calendrier (et non en la tapant manuellement), combinez les deux paramètres suivants :

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

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

Manually open the calendar

Pour ouvrir le calendrier de manière programmatique :

picker.open();

Ou utilisez l'alias :

picker.show(); // équivalent à 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);