MaskedTextField

De MaskedTextField component biedt een configureerbare tekstinvoer die formatteerregels en validatie af enforced. Het is goed geschikt voor apps die gestructureerde invoer vereisen, zoals financiële, e-commerce en zorgsystemen.

Basisprincipes

De MaskedTextField kan worden geïnstantieerd met of zonder parameters. Je kunt een initiële waarde, een label, een placeholder-tekst en een listener definiëren in geval de waarde verandert.

MaskedTextField field = new MaskedTextField("Account ID");
field.setMask("ZZZZ-0000")
  .setHelperText("Mask: ZZZZ-0000 - bijvoorbeeld: SAVE-2025")

Mask regels

De MaskedTextField formatteert tekstinvoer met behulp van een masker - een tekenreeks die definieert welke tekens op elke positie zijn toegestaan. Dit zorgt voor consistente, gestructureerde invoer voor dingen zoals telefoonnummers, postcodes en ID-formaten.

Programma-matig maskers toepassen

Om tekenreeksen met dezelfde maskersyntaxis buiten een veld te formatteren, bijvoorbeeld wanneer gegevens in een Table worden weergegeven, gebruik de MaskDecorator hulpprogrammaklas.

Ondersteunde masker-karakters

Karakter	Beschrijving
`X`	Elk afdrukbaar teken
`a`	Elk alfabetisch teken (hoofdletter of kleine letter)
`A`	Elk alfabetisch teken; kleine letters worden omgezet naar hoofdletters
`0`	Elk cijfer (0–9)
`z`	Elk cijfer of letter (hoofdletter of kleine letter)
`Z`	Elk cijfer of letter; kleine letters worden omgezet naar hoofdletters

Alle andere tekens in het masker worden als letterlijke tekens behandeld en moeten precies worden getypt. Bijvoorbeeld, een masker zoals XX@XX vereist dat de gebruiker een @ in het midden invoert.

Ongeldige tekens worden stilzwijgend genegeerd.
Korte invoer wordt opgevuld met spaties.
Lange invoer wordt ingekort om in het masker te passen.

Voorbeelden

field.setMask("(000) 000-0000");     // Voorbeeld: (123) 456-7890
field.setMask("A00 000");            // Voorbeeld: A1B 2C3 (Canadese postcode)
field.setMask("ZZZZ-0000");          // Voorbeeld: ABCD-1234
field.setMask("0000-0000-0000-0000");// Voorbeeld: 1234-5678-9012-3456

Volledige invoer toegestaan

Als het masker alleen X bevat, gedraagt het veld zich als een standaard TextField, wat elke afdrukbare invoer mogelijk maakt. Dit is nuttig wanneer je de mogelijkheid wilt behouden om te formatteren zonder strikte karakterregels toe te passen.

Toon Code

MaskedTextFieldView.java

Validatiepatronen

Terwijl maskers de structuur van de invoer definiëren, kun je ze combineren met validatiepatronen om specifiekere invoerregels af te dwingen. Dit voegt een extra laag van client-side validatie toe met behulp van reguliere expressies.

Gebruik de setPattern() methode om een aangepaste reguliere expressie toe te passen:

field.setPattern("[A-Za-z0-9]{10}"); // Dwingt een alfanumerieke code van 10 tekens af

Dit zorgt ervoor dat de invoer niet alleen overeenkomt met het masker, maar ook voldoet aan een gedefinieerde structuur, zoals lengte of toegestane tekens.

Dit is vooral nuttig wanneer:

Het masker te veel flexibiliteit toestaat
Je exact lengte of een specifiek formaat wilt afdwingen (bijvoorbeeld hex, Base64, UUID)

Formaat van reguliere expressie

Het patroon moet een geldige JavaScript reguliere expressie zijn, zoals gebruikt door het RegExp type. Je kunt meer details vinden in de HTML patroon attribuut documentatie.

De waarde herstellen

De MaskedTextField bevat een herstel functie die de waarde van het veld terugzet naar een vooraf gedefinieerde of oorspronkelijke staat. Dit kan nuttig zijn voor het ongedaan maken van gebruikerswijzigingen of het terugkeren naar een standaardinvoer.

field.setRestoreValue("ABC123");
field.restoreValue();

Manieren om de waarde te herstellen

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

Je kunt de waarde om te herstellen instellen met setRestoreValue(). Als er geen herstelwaarde is ingesteld, gaat het veld terug naar de initiële waarde op het moment dat het werd weergegeven.

Toon Code

MaskedTextFieldRestoreView.java