MaskedTimeField

De MaskedTimeField is een tekstinvoer waarmee gebruikers tijden kunnen invoeren als nummers en automatisch de invoer op basis van een gedefinieerde maskering formatteert wanneer het veld zijn focus verliest. Het masker specificeert het verwachte tijdsformaat, en helpt zowel bij de invoer als bij de weergave. De component ondersteunt flexibele parsing, validatie, lokalisatie en waardeherstel voor consistente tijdsbehandeling.

Op zoek naar een datum invoer?

De MaskedTimeField is gebouwd voor alleen-tijd invoer. Als je op zoek bent naar een component om data met een vergelijkbare masker-gebaseerde opmaak te verwerken, kijk dan naar de MaskedDateField.

De MaskedTimeField kan met of zonder parameters worden geïnitialiseerd. Je kunt een initiële waarde, een label, een placeholder en een gebeurtenisluisteraar voor waarde- wijzigingen definiëren.

Toon Code

MaskedTimeFieldView.java

Masker regels

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

Maskers programmatically toepassen

Om tijden met dezelfde masker syntaxis buiten een veld te formatteren of te parsen, gebruik de MaskDecorator hulpprogrammaklasse.

Tijd formaat indicaties

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

Modifiers

Modifiers verfijnen de weergave van tijdcomponenten:

Modifier	Beschrijving
`z`	Voorloop nul
`s`	Korte tekstrepresentatie
`l`	Lange tekstrepresentatie
`p`	Samengepakt nummer
`d`	Decimaal (standaardformaat)

Deze bieden flexibele en locale-vriendelijke tijdopmaak.

Tijd formaat lokalisatie

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.

Parsing logica

De MaskedTimeField parseert gebruikersinvoer op basis van het gedefinieerde tijdmasker. Het accepteert zowel volledige als afgekorte numerieke invoer met of zonder scheidingstekens, wat flexibele invoer mogelijk maakt terwijl geldige tijden worden gegarandeerd. De parsinggedrag hangt af van de volgorde van het formaat dat door het masker is gedefinieerd (bijv. %Hz:%mz voor uur/minuut). Dit formaat bepaalt hoe numerieke reeksen worden geïnterpreteerd.

Voorbeeld parsing 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`

Instellen van min/max beperkingen

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

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

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

Herstellen van de waarde

De MaskedTimeField bevat een herstelfunctie die de waarde van het veld reset naar een vooraf gedefinieerde of originele 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

Programmatically, door restoreValue() aan te roepen
Via toetsenbord, door op ESC te drukken (dit is de standaardhersteltoets tenzij vervangen door een gebeurtenisluisteraar)

Toon Code

MaskedTimeFieldRestoreView.java

Validatie patronen

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

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.

Formaat van Reguliere Expressie

Het patroon moet de JavaScript RegExp-syntaxis volgen zoals gedocumenteerd hier.

Notities over Input Afhandeling

Het veld probeert numerieke tijdsinputs te parseren en formatteren op basis van het huidige masker. Gebruikers kunnen echter nog steeds handmatig waarden invoeren die niet aan het verwachte formaat voldoen. Als de invoer syntactisch geldig maar semantisch onjuist of onparseerbaar is (bijv. 99:99), kan deze patrooncontroles doorstaan maar de logische validatie mislukken. Je moet altijd de invoerwaarde in je app-logica valideren, zelfs als een reguliere expressie patroon is ingesteld, om ervoor te zorgen dat de tijd zowel correct is opgemaakt als betekenisvol is.

Tijdkiezer

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

Toon Code

MaskedTimeFieldPickerView.java

Toegang tot de kiezer

Je kunt de tijdkiezer openen met getPicker():

TimePicker picker = field.getPicker();

Toon/verberg het icoon van 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 interactie heeft met het veld (bijv. klikt, Enter of pijltjestoetsen indrukt):

picker.setAutoOpen(true);

Dwing Selectie via de Kiezer

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

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

Deze opzet garandeert dat alle tijdinvoer via de kiezer UI komt, wat nuttig is wanneer je strikte formatcontrole wilt en parserproblemen van getypte invoer wilt elimineren.

Handmatig de kiezer openen

Om de tijdkiezer programatisch te openen:

picker.open();

Of gebruik de alias:

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

Instellen van de stap van de kiezer

Je kunt het interval tussen selecteerbare tijden in de kiezer definiëren 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));

Stap Beperking

De stap moet een gehele uur of een volledige dag gelijkmatig verdelen. Anders wordt er een uitzondering gegenereerd.

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