MaskedTimeField

De MaskedTimeField is een tekstinvoer waarmee gebruikers tijden kunnen invoeren als getallen en automatisch de invoer opmaakt op basis van een gedefinieerde masker wanneer het veld de focus verliest. De masker specificeert het verwachte tijdformaat, wat zowel de invoer als de weergave begeleidt. De component ondersteunt flexibele parsering, validatie, lokalisatie en waardeherstel voor consistente tijdsafhandeling.

Basisprincipes

Op zoek naar datum invoer?

De MaskedTimeField is ontworpen voor tijd-only invoer. Als je een component zoekt om datums met een vergelijkbare masker-gebaseerde opmaak te behandelen, 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 gebeurtenislijster voor waarde wijzigingen definiëren.

Toon Code

MaskedTimeFieldView.java

Masker regels

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.

Maskers programmatically toepassen

Om tijden met dezelfde masker syntaxis buiten een veld op te maken of te parseren, gebruik de MaskDecorator utility klasse.

Tijd formaatindicatoren

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 vullen
`s`	Korte tekst representatie
`l`	Lange tekst representatie
`p`	Samengevoegd getal
`d`	Decimaal (standaardformaat)

Deze zorgen voor flexibele en lokale 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 beïnvloedt hoe AM/PM-indicatoren worden weergegeven, hoe scheidingstekens worden behandeld en hoe waarden worden geparsed.

Parseringslogica

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

Voorbeeld parseringsscenario'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 min/max beperkingen

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. Invoeren buiten het gedefinieerde bereik worden als ongeldig beschouwd.

Waarde herstellen

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 terug te keren naar een standaardtijd.

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

Manieren om de waarde te herstellen

Programmatig, door restoreValue() aan te roepen
Via toetsenbord, door ESC in te drukken (dit is de standaard hersteltoets tenzij overschreven door een gebeurtenislijster)

Toon Code

MaskedTimeFieldRestoreView.java

Validatiepatronen

Je kunt client-side validatieregels toepassen met behulp van reguliere expressies met de methoden 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 Expressie Formaat

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

Opmerkingen over Invoerverwerking

Het veld probeert numerieke tijdinvoer te parseren en op te maken op basis van de 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 is (bijv. 99:99), kan het patrooncontroles doorstaan maar de logische validatie mislukken. Je moet altijd de invoerwaarde in je app-logica valideren, zelfs als er een regulier expressiepatroon is ingesteld, om ervoor te zorgen dat de tijd zowel correct geformatteerd 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 toegang krijgen tot de tijdkiezer 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

Auto-open gedrag

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

picker.setAutoOpen(true);

Selectie Dwingen via de Kiezer

Om ervoor te zorgen dat gebruikers alleen een tijd kunnen selecteren met 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 kiezer UI komt, wat nuttig is wanneer je strikte formatcontrole wilt en parseringsproblemen van ingetikte invoer wilt uitsluiten.

Handmatig de kiezer openen

Om de tijdkiezer programmatig te openen:

picker.open();

Of gebruik de alias:

picker.show(); // hetzelfde 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 tijdopties zijn - ideaal voor scenario's zoals planning in blokken van 15 minuten.

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

Stap Beperking

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

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