MaskedTimeField

Le MaskedTimeField est une entrée de texte qui permet aux utilisateurs d'entrer des heures 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 spécifie le format d'heure attendu, guidant à la fois l'entrée et l'affichage. Le composant prend en charge le parsing flexible, la validation, la localisation et la restauration de valeur pour un traitement du temps cohérent.

Bases

Vous cherchez une entrée de date ?

Le MaskedTimeField est conçu pour une saisie uniquement horaire. Si vous cherchez un composant pour gérer les dates avec un formatage basé sur des masques similaire, jetez un œil au MaskedDateField.

Le MaskedTimeField 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

Règles de masquage

Le MaskedTimeField utilise des indicateurs de format pour définir comment le temps est analysé et affiché. Chaque indicateur de format commence par un % suivi d'une lettre représentant un composant horaire.

Indicateurs de format de temps

Format	Description
`%H`	Heure (24 heures)
`%h`	Heure (12 heures)
`%m`	Minute
`%s`	Seconde
`%p`	AM/PM

Modificateurs

Les modificateurs affinent l'affichage des composants horaires :

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

Cela permet un formatage du temps flexible et adapté aux différentes locales.

Localisation du format de temps

Le MaskedTimeField prend en charge la localisation en définissant la locale appropriée. Cela garantit que l'entrée et la sortie de temps correspondent aux conventions régionales.

field.setLocale(Locale.GERMANY);

Cela affecte la manière dont les indicateurs AM/PM sont affichés, comment les séparateurs sont gérés, et comment les valeurs sont analysées.

Logique d'analyse

Le MaskedTimeField analyse l'entrée utilisateur en fonction du masque horaire 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 heures valides. Le comportement d'analyse dépend de l'ordre de format défini par le masque (par exemple, %Hz:%mz pour heure/minute). Ce format détermine comment les séquences numériques sont interprétées.

Scénarios d'analyse exemples

Saisie	Masque	Interprété Comme
`900`	`%Hz:%mz`	`09:00`
`1345`	`%Hz:%mz`	`13:45`
`0230`	`%hz:%mz %p`	`02:30 AM`
`1830`	`%hz:%mz %p`	`06:30 PM`

Définir des contraintes min/max

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

field.setMin(LocalTime.of(8, 0));
field.setMax(LocalTime.of(18, 0));

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

Restauration de la valeur

Le MaskedTimeField comprend une fonctionnalité de restauration qui réinitialise la valeur du champ à un état prédéfini ou d'origine. Cela peut être utile pour annuler des modifications ou revenir à une heure par défaut.

field.setRestoreValue(LocalTime.of(12, 0));
field.restoreValue();

Façons de restaurer la valeur

Programmatique, en appelant restoreValue()
Via le clavier, en appuyant sur ESC (c'est la clé de restauration par défaut, sauf si remplacée par un écouteur d'événements)

Afficher le code

Java

Modèles de validation

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

field.setPattern("^\\d{2}:\\d{2}$");

Ce modèle garantit que seules les valeurs correspondant au format HH:mm (deux chiffres, deux-points, deux chiffres) sont considérées comme valides.

Format d'expression régulière

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

Remarques sur le traitement des entrées

Le champ tente d'analyser et de formater les entrées horaires 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 ex. 99:99), elle peut passer les contrôles 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 garantir que l'heure est à la fois correctement formatée et significative.

Sélecteur d'heure

Le MaskedTimeField comprend un sélecteur d'heure intégré qui permet aux utilisateurs de sélectionner une heure 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 requises.

Afficher le code

Java

Accéder au sélecteur

Vous pouvez accéder au sélecteur d'heure en utilisant getPicker() :

TimePicker picker = field.getPicker();

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

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

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

Comportement d'ouverture automatique

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 utilise les flèches) :

picker.setAutoOpen(true);

Imposer la sélection via le sélecteur

Pour s'assurer que les utilisateurs peuvent uniquement choisir une heure en utilisant le sélecteur (et non la saisir manuellement), combinez les deux paramètres suivants :

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

Cette configuration garantit que toutes les entrées horaires 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 liés à des saisies manuelles.

Ouvrir manuellement le sélecteur

Pour ouvrir le sélecteur d'heure de manière programmatique :

picker.open();

Ou utilisez l'alias :

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

Définir le pas de sélection du sélecteur

Vous pouvez définir l'intervalle entre les heures sélectionnables dans le sélecteur en utilisant setStep(). Cela vous permet de contrôler le niveau de granularité des options horaires—idéal pour des scénarios comme la planification à intervalles de 15 minutes.

field.getPicker().setStep(Duration.ofMinutes(15));

Contraintes de pas

Le pas doit diviser uniformément une heure ou une journée entière. Sinon, une exception sera déclenchée.

Cela garantit que la liste déroulante contient des valeurs prévisibles et équidistantes comme 09:00, 09:15, 09:30, etc.