MaskedTimeField

De MaskedTimeField is een tekstinvoer waarmee gebruikers tijden als nummers kunnen invoeren en de invoer automatisch wordt opgemaakt op basis van een gedefinieerde maskering wanneer het veld de focus verliest. Het masker specificeert het verwachte tijdformaat, dat zowel de invoer als weergave helpt. De component ondersteunt flexibele parsing, validatie, lokalisatie en waardeherstellen voor consistente tijdsafhandeling.

Basisprincipes

Op zoek naar invoer voor datums?

De MaskedTimeField is ontworpen voor enkel tijd invoer. Als je op zoek bent naar een component om datums met vergelijkbare maskergebaseerde opmaak te verwerken, kijk dan naar de MaskedDateField.

De MaskedTimeField kan worden geïnstantieerd met of zonder parameters. Je kunt een initiële waarde, een label, een plaatsaanduiding en een eventlistener voor waarde veranderen definiëren.

Toon Code

Java

Maskerregels

De MaskedTimeField gebruikt formaatindicatoren om te definiëren hoe tijd wordt geparsed en weergegeven. Elke formaatindicator begint met een % gevolgd door een letter die een tijdcomponent vertegenwoordigt.

Tijdformaatindicatoren

Formaat	Beschrijving
`%H`	Uur (24-uurs)
`%h`	Uur (12-uurs)
`%m`	Minuut
`%s`	Seconde
`%p`	AM/PM

Modifiers

Modifiers verfijnen de weergave van tijdcomponenten:

Modifier	Beschrijving
`z`	Null-vulling
`s`	Korte tekstrepresentatie
`l`	Lange tekstrepresentatie
`p`	Gecomprimeerd nummer
`d`	Decimaal (standaardformaat)

Deze maken flexibele en plaatselijke tijdsopmaak mogelijk.

Lokalisatie van tijdformaat

De MaskedTimeField ondersteunt lokalisatie door de juiste locale in te stellen. Dit zorgt ervoor dat tijdinvoer en -uitvoer overeenkomen met regionale conventies.

field.setLocale(Locale.GERMANY);

Dit heeft invloed op hoe AM/PM-indicatoren worden weergegeven, hoe scheidingstekens worden behandeld en hoe waarden worden geparsed.

Parsinglogica

De MaskedTimeField parseert gebruikersinvoer op basis van het gedefinieerde tijdmasker. Het accepteert zowel complete als afgebroken numerieke invoer met of zonder scheidingstekens, waardoor flexibele invoer mogelijk is, terwijl ervoor wordt gezorgd dat het geldige tijden zijn. De parseringsgedrag hangt af van de formele volgorde die door het masker is gedefinieerd (bijvoorbeeld %Hz:%mz voor uur/minuut). Dit formaat bepaalt hoe numerieke reeksen worden geïnterpreteerd.

Voorbeeld van parse-scenario's

Invoer	Masker	Geïnterpreteerd Als
`900`	`%Hz:%mz`	`09:00`
`1345`	`%Hz:%mz`	`13:45`
`0230`	`%hz:%mz %p`	`02:30 AM`
`1830`	`%hz:%mz %p`	`06:30 PM`

Min/max-beperkingen instellen

Je kunt het toegestane tijdsbereik in een MaskedTimeField beperken met de methoden setMin() en setMax():

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

Beide methoden accepteren waarden van het type java.time.LocalTime. Invoer buiten het gedefinieerde bereik wordt als ongeldig beschouwd.

Waardeherstel

De MaskedTimeField bevat een herstelfunctie die de waarde van het veld reset naar een vooraf gedefinieerde of oorspronkelijke staat. Dit kan nuttig zijn om wijzigingen ongedaan te maken of om terug te keren naar een standaardtijd.

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

Manieren om de waarde te herstellen

Programma-technisch, door restoreValue() aan te roepen
Via het toetsenbord, door op ESC te drukken (dit is de standaardhersteltoets, tenzij overschreven door een eventlistener)

Toon Code

Java

Validatiepatronen

Je kunt client-side validatieregels toepassen met reguliere expressies met de methode setPattern():

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

Dit patroon zorgt ervoor dat alleen waarden die overeenkomen met het HH:mm formaat (twee cijfers, dubbele punt, twee cijfers) als geldig worden beschouwd.

Reguliere expressieformaat

Het patroon moet voldoen aan de syntaxis van JavaScript RegExp zoals gedocumenteerd hier.

Opmerkingen over invoerhandling

Het veld probeert numerieke tijdinvoeren te parseren en op te maken op basis van het huidige masker. Gebruikers kunnen echter nog steeds handmatig waarden invoeren die niet overeenkomen met het verwachte formaat. Als de invoer syntactisch geldig is, maar semantisch onjuist of niet parseerbaar (bijvoorbeeld 99:99), kan het patrooncontroles doorstaan maar foutieve logische validatie krijgen. Je moet de invoerwaarde altijd valideren in de logica van je app, zelfs als er een regulier expressiepatroon is ingesteld, om ervoor te zorgen dat de tijd zowel correct is opgemaakt als betekenisvol.

Tijdkiezer

De MaskedTimeField bevat een ingebouwde tijdkiezer waarmee gebruikers visueel een tijd kunnen selecteren, in plaats van deze in te voeren. Dit verbetert de bruikbaarheid voor minder technische gebruikers of wanneer een nauwkeurige invoer vereist is.

Toon Code

Java

Toegang tot de kiezer

Je kunt toegang krijgen tot de tijdkiezer met getPicker():

TimePicker picker = field.getPicker();

Toon/verberg het icon voor de kiezer

Gebruik setIconVisible() om het klokicoon naast het veld te tonen of te verbergen:

picker.setIconVisible(true); // toont het icoon

Automatisch openen gedrag

Je kunt de kiezer configureren om automatisch te openen wanneer de gebruiker met het veld interactie heeft (bijv. klikt, op Enter drukt of pijltoetsen gebruikt):

picker.setAutoOpen(true);

Dwing selectie via de kiezer

Om ervoor te zorgen dat gebruikers alleen een tijd kunnen selecteren via de kiezer (en niet handmatig typen), combineer je de volgende twee instellingen:

field.getPicker().setAutoOpen(true); // Opent de kiezer bij gebruikersinteractie
field.setAllowCustomValue(false);    // Schakelt handmatige tekstinvoer uit

Deze opstelling garandeert dat alle tijdinvoer via de UI van de kiezer komt, wat nuttig is wanneer je strikte opmaakcontrole wilt en parseringsproblemen van ingevoerde tekst wilt vermijden.

Handmatig de kiezer openen

Om de tijdkiezer programmatically te openen:

picker.open();

Of gebruik de alias:

picker.show(); // hetzelfde als open()

De stap van de kiezer instellen

Je kunt het interval tussen de selecteerbare tijden in de kiezer instellen met setStep(). Dit stelt je in staat om te controleren hoe gedetailleerd de tijdsopties zijn—ideaal voor scenario's zoals plannen in blokken van 15 minuten.

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

Stapbeperkingen

De stap moet gelijkmatig een uur of een hele dag delen. Anders wordt een uitzondering opgegooid.

Dit zorgt ervoor dat de dropdownlijst voorspelbare, gelijkmatig verdeelde waarden bevat zoals 09:00, 09:15, 09:30, enz.