MaskedDateField

Le MaskedDateField est un champ de saisie de texte qui permet aux utilisateurs d'entrer des dates sous forme de chiffres et formate automatiquement l'entrée en fonction d'un masque défini lorsque le champ perd le focus. Le masque spécifie le format de date attendu, guidant à la fois l'entrée et l'affichage. Le composant prend en charge le parsing, la validation, la localisation et la restauration des valeurs flexibles pour un traitement des dates cohérent et spécifique à la région.

Bases

Vous cherchez une entrée de temps ?

Le MaskedDateField se concentre uniquement sur les valeurs de date. Si vous avez besoin d'un composant similaire pour saisir et formater l'heure, envisagez plutôt le MaskedTimeField.

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

MaskedDateFieldView.java

Règles de masque

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 motifs 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 la norme ISO : YYYY-MM-DD)

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

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.

Application des masques par programmation

Pour formater ou analyser les dates avec la même syntaxe de masque en dehors d'un champ, utilisez la classe utilitaire MaskDecorator.

Indicateurs de format de date

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

Modificateurs

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 compressé
`d`	Décimal (format par défaut)

Ceci peut être combiné pour construire une grande variété de masques de date.

Localisation du format de date

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 de l'utilisateur.

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 une java.util.Locale et ajuste automatiquement à la fois le formatage et l'analyse :

dateField.setLocale(Locale.FRANCE);

Logiciel de parsing

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 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, en supposant qu'aujourd'hui soit le 15 septembre 2012, voici comment diverses entrées seraient interprétées :

Scénarios d'exemple d'analyse

Entrée	YMD (ISO)	MDY (US)	DMY (EU)
`1`	Un chiffre unique est toujours interprété comme un nombre de jour dans le mois en cours, donc ce serait le 1er septembre 2012.	Pareil que YMD	Pareil que YMD
`12`	Deux chiffres sont toujours interprétés comme un nombre de jour dans le mois en cours, donc ce serait le 12 septembre 2012.	Pareil que YMD	Pareil 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 ce serait le 12 janvier 2012.	Pareil que YMD	Trois chiffres sont interprétés comme un numéro de jour à 1 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 MMDD, donc ce serait le 4 octobre 2012.	Pareil que YMD	Quatre chiffres sont interprétés comme DDMM, donc ce serait le 10 avril 2012.
`020304`	Six chiffres sont interprétés comme YYMMDD, donc ce serait le 4 mars 2002.	Six chiffres sont interprétés comme MMDDYY, donc ce serait le 3 février 2004.	Six chiffres sont interprétés comme DDMMYY, donc ce 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 ce serait le 6 décembre 2012. Note : Tous les caractères sauf les lettres et les chiffres sont considérés comme des délimiteurs valides.	Pareil que YMD	Deux nombres séparés par un délimiteur sont interprétés comme DD/MM, donc ce serait le 12 juin 2012.
`3/4/5`	5 avril 2012	4 mars 2005	3 avril 2005

Analyse de date textuelle 25.11

Par défaut, le MaskedDateField n'accepte que les entrées numériques pour les dates. Cependant, vous pouvez activer l'analyse de dates textuelles pour permettre aux utilisateurs d'entrer les 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);

Substitution des noms de mois

Lorsque le parsing textuel est activé, vous pouvez utiliser des modificateurs spéciaux dans votre masque pour accepter les noms de mois au lieu 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 continuera à accepter les entrées numériques comme solution de repli.

Exemples

Masque	Entrée	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 repli fonctionne toujours

info

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

Décoration des noms de jours

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

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

Les Noms de Jours Nécessitent un Jour Numérique

Lorsque vous utilisez des noms de jours 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.

Exemples

Masque	Entrée	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 pris en charge sous forme courte (Lun, Mar, Mer, Jeu, Ven, Sam, Dim) et sous forme longue (Lundi, Mardi, etc.).

Règles supplémentaires d'analyse

L'analyse textuelle des dates comprend plusieurs fonctionnalités utiles :

Insensible à la casse : Les entrées telles que LUNDI 09/01/25, lundi 09/01/25 ou Lundi 09/01/25 fonctionnent toutes de la même manière.
Consciente de la locale : Les noms de mois et de 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 de jour

Définir des contraintes min/max

Vous pouvez restreindre la plage de dates autorisées dans un MaskedDateField à l'aide des 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.

Restauration de la valeur

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

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

Façons de restaurer la valeur

Programmatique, 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(), passant une instance de LocalDate.

Afficher le code

MaskedDateFieldRestoreView.java

Modèles de validation

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/DD/YYYY (deux chiffres, barre oblique, deux chiffres, barre oblique, quatre chiffres) sont considérées comme valides.

Format de l'expression régulière

Le modèle doit suivre la syntaxe JavaScript RegExp comme documenté ici.

Notes sur la gestion des entrées

Le champ essaie d'analyser et de formater les entrées numériques des dates 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 lors de la validation logique. Vous devez toujours valider la valeur d'entrée dans la logique de votre application, même si un modèle d'expression régulière est défini, pour garantir que la date est à la fois correctement formatée et significative.

Sélecteur de date

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'utilisabilité pour les utilisateurs moins techniques ou lorsque des entrées précises sont nécessaires.

Afficher le code

MaskedDateFieldPickerView.java

Accéder au sélecteur

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

DatePicker picker = dateField.getPicker();

Afficher/masquer l'icône du sélecteur

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

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

Comportement d'ouverture automatique

Vous pouvez configurer le sélecteur pour s'ouvrir 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 vous assurer que les utilisateurs ne peuvent sélectionner une date qu'à l'aide du sélecteur de calendrier (et non en en saisissant manuellement une), combinez les deux paramètres 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 utilisateur du sélecteur, ce qui est utile lorsque vous souhaitez un contrôle strict du format et éliminer les problèmes d'analyse des entrées saisies.

Ouvrir manuellement le calendrier

Pour ouvrir le calendrier programatiquement :

picker.open();

Ou utilisez l'alias :

picker.show(); // identique à open()

Afficher les semaines dans le calendrier

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

picker.setShowWeeks(true);