MaskedTextField

De MaskedTextField component biedt een configureerbare tekstinvoer die opmaakregels en validatie afdwingt. Het is goed geschikt voor apps die gestructureerde invoer vereisen, zoals financiële systemen, e-commerce en gezondheidszorg.

Deze component kan worden geïnstantieerd met of zonder parameters. Je kunt een iniële waarde, een label, een voorbeeldtekst en een luisteraar definiëren in geval de waarde verandert.

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

Maskregels

De MaskedTextField formatteert tekstinvoer met een mask - een string die definieert welke tekens op elke positie zijn toegestaan. Dit zorgt voor consistente, gestructureerde invoer voor zaken als telefoonnummers, postcodes en ID-formaten.

Toepassen van masks via programmering

Om strings met dezelfde mask-syntaxis buiten een veld te formatteren, bijvoorbeeld wanneer gegevens worden weergegeven in een Table, gebruik de MaskDecorator utility-klasse.

Ondersteunde masktekens

Teken	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 mask worden behandeld als letterlijke tekens en moeten precies worden getypt. Bijvoorbeeld, een mask 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 afgekapt om in het mask 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 mask alleen X bevat, gedraagt het veld zich als een standaard TextField, wat elke afdrukbare invoer toelaat. Dit is nuttig wanneer je de mogelijkheid wilt behouden om te formatteren zonder strikte tekenregels toe te passen.

Toon Code

MaskedTextFieldView.java

Validatiepatronen

Terwijl masks de structuur van de invoer definiëren, kun je ze combineren met validatiepatronen om meer specifieke invoerregels af te dwingen. Dit voegt een extra laag 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 10-teken alfanumerieke code af

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

Dit is vooral nuttig wanneer:

Het mask te veel flexibiliteit toestaat
Je een exacte lengte of een specifiek formaat wilt afdwingen (bijv. 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 patroonattributen documentatie.

Herstellen van de waarde

De MaskedTextField omvat een herstelfunctie die de waarde van het veld reset naar een vooraf gedefinieerde of originele staat. Dit kan nuttig zijn om gebruikerswijzigingen terug te draaien of terug te keren naar een standaardinvoer.

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

Manieren om de waarde te herstellen

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

Je kunt de waarde die moet worden hersteld instellen met setRestoreValue(). Als er geen herstelwaarde is ingesteld, keert het veld terug naar de initiële waarde op het moment dat het werd weergegeven.

Toon Code

MaskedTextFieldRestoreView.java