MaskedTimeField

De MaskedTimeField is een tekstinvoerveld ontworpen voor nauwkeurige, gestructureerde tijdinvoer. Het stelt gebruikers in staat om tijden als getallen in te voeren en formatteert automatisch de invoer op basis van een gedefinieerde maskering wanneer het veld de focus verliest. De maskering is een string die het verwachte tijdformaat specificeert, ter begeleiding van zowel invoer als weergave.

Deze component ondersteunt flexibele parsing, validatie, lokalisatie en waardeherstel. Het is vooral nuttig in tijdgevoelige formulieren zoals schema's, urenstaten en reserveringen.

Op zoek naar datum invoer?

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

Basisprincipes

De MaskedTimeField kan worden geïnstantieerd met of zonder parameters. Je kunt een initiële waarde, een label, een tijdelijke aanduiding en een evenementlistener voor waarde wijzigingen definiëren.

Toon code

Java

Maskerregels

De MaskedTimeField gebruikt formateringsindicatoren om te definiëren hoe tijd wordt geparsed en weergegeven. Elke formateringsindicator 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`	Voorloopnullen
`s`	Korte tekstweergave
`l`	Lange tekstweergave
`p`	Samengevoegd nummer
`d`	Decimaal (standaard formaat)

Deze zorgen voor flexibele en locale-vriendelijke tijdopmaak.

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

Parsinglogica

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

Voorbeeld van parsingscenario'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`

Minimale/maximale beperkingen instellen

Je kunt de 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.

Waardeherstel

De MaskedTimeField bevat een herstelfunctie die de waarde van het veld terugzet 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

Programmatic, door restoreValue() aan te roepen
Via toetsenbord, door ESC in te drukken (dit is de standaardhersteltoets, tenzij overschreven door een evenementlistener)

Toon code

Java

Validatiepatronen

Je kunt client-side validatieregels toepassen met behulp van 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.

Formaat van reguliere expressies

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

Opmerkingen over invoerhandling

Het veld probeert numerieke tijdinvoeren te parseren en op te maken op basis van de huidige maskering. Echter, gebruikers kunnen nog steeds handmatig waarden invoeren die niet overeenkomen met het verwachte formaat. Als de invoer syntactisch geldig maar semantisch onjuist of onparseerbaar is (bijv. 99:99), kan het patroonchecks doorstaan maar faalt in logische validatie. Je moet de invoerwaarde altijd valideren in je app-logica, 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 die gebruikers in staat stelt om visueel een tijd te selecteren, in plaats van deze in te typen. Dit verbetert de bruikbaarheid voor minder technische gebruikers of wanneer nauwkeurige invoer vereist is.

Toon code

Java

Toegang tot de kiezer

Je kunt de tijdkiezer krijgen 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 zo configureren dat deze automatisch opent wanneer de gebruiker interactie heeft met het veld (bijv. klikt, op Enter of pijltjestoetsen drukt):

picker.setAutoOpen(true);

Dwingen tot selectie via de kiezer

Om ervoor te zorgen dat gebruikers alleen een tijd kunnen selecteren met behulp van 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 picker UI komt, wat nuttig is wanneer je strikte formaten wilt controleren en parseringsproblemen van getypte invoer wilt elimineren.

Handmatig de kiezer openen

Om de tijdkiezer programmatisch te openen:

picker.open();

Of gebruik de alias:

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

Stapgrootte van de kiezer instellen

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 plannen in blokken van 15 minuten.

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

Stapbeperking

De stap moet gelijkmatig een uur of een volle dag verdelen. Anders wordt er een uitzondering gegooid.

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