MaskedTimeField

Le MaskedTimeField est un champ 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 de temps attendu, guidant à la fois l'entrée et l'affichage. Le composant prend en charge l'analyse flexible, la validation, la localisation et la restauration de valeur pour un traitement temporel cohérent.

Bases

Vous cherchez une entrée de date ?

Le MaskedTimeField est conçu pour une entrée uniquement temporelle. Si vous cherchez un composant pour gérer des 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

MaskedTimeFieldView.java

Règles de masque

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

Application de masques par programmation

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

Indicateurs de format temporel

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 temporels :

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

Cela permet un formatage du temps flexible et adapté aux régions.

Localisation du formatage temporel

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

field.setLocale(Locale.GERMANY);

Cela affecte la façon 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 temporel 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 d'exemple

Entrée	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 à l'aide des 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 inclut une fonctionnalité de restauration qui réinitialise la valeur du champ à un état préalablement défini ou original. Cela peut être utile pour annuler des changements ou revenir à une heure par défaut.

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

Méthodes pour restaurer la valeur

Par programmation, en appelant restoreValue()
Via le clavier, en appuyant sur ESC (c'est la touche de restauration par défaut à moins qu'elle ne soit remplacée par un écouteur d'événements)

Afficher le code

MaskedTimeFieldRestoreView.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 motif garantit que seules les valeurs correspondant au format HH:mm (deux chiffres, deux-points, deux chiffres) sont considérées comme valables.

Format d'expression régulière

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

Remarques sur la gestion des entrées

Le champ tente d'analyser et de formater les entrées de temps numériques 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 inanalysable (par exemple 99:99), elle peut passer les vérifications de motif mais échouer la validation logique. Vous devez toujours valider la valeur d'entrée dans votre logique d'application, même si un motif d'expression régulière est défini, pour garantir que l'heure est à la fois correctement formatée et significative.

Sélecteur horaire

Le MaskedTimeField inclut un sélecteur d'heure intégré qui permet aux utilisateurs de sélectionner une heure visuellement, au lieu de la saisir. Cela améliore l'utilisabilité pour les utilisateurs moins techniques ou lorsque des entrées précises sont requises.

Afficher le code

MaskedTimeFieldPickerView.java

Accéder au sélecteur

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

TimePicker picker = field.getPicker();

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

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

picker.setIconVisible(true); // montre 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 utilise les flèches) :

picker.setAutoOpen(true);

Forcer la sélection via le sélecteur

Pour vous assurer que les utilisateurs ne peuvent sélectionner une heure qu'à l'aide du sélecteur (et ne pas en saisir une 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 l'entrée de texte manuelle

Cette configuration garantit que toutes les saisies d'heures passent par 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 des saisies manuelles.

Ouvrir manuellement le sélecteur

Pour ouvrir le sélecteur d'heure par programmation :

picker.open();

Ou utilisez l'alias :

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

Définir l'étape 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 la granularité des options temporelles—idéal pour des scénarios comme la planification par blocs de 15 minutes.

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

Contrainte d'étape

L'étape doit diviser uniformément une heure ou une journée entière. Sinon, une exception sera levée.

Cela garantit que la liste déroulante contient des valeurs prévisibles et régulièrement espacées comme 09:00, 09:15, 09:30, etc.