MaskedNumberField

Het MaskedNumberField is een tekstinvoer ontworpen voor het consistent formatteren van numerieke invoer, op basis van een gedefinieerde mask. Het is handig voor financiële formulieren, prijsvelden, of elke invoer waar precisie en leesbaarheid belangrijk zijn.

Deze component kan worden aangemaakt met of zonder parameters. Het ondersteunt nummerformattering, lokalisatie van decimale/groeperingskarakters en optionele waarde-beperkingen zoals minimums of maximums. Het ondersteunt ook het instellen van een initiële waarde, een label, een placeholder, en een gebeurtenislistener om te reageren op waarde wijzigingen.

Het onderstaande voorbeeld toont een Fooi Calculator die MaskedNumberField gebruikt voor intuïtieve numerieke invoer. Eén veld is geconfigureerd om een geformatteerd rekeningbedrag te accepteren, terwijl de andere een whole-number fooi percentage vastlegt.

Mask regels

Het MaskedNumberField gebruikt een mask string om te controleren hoe numerieke invoer wordt geformatteerd en weergegeven. Iedere karakter in het mask definieert een specifiek formatteringsgedrag, waardoor nauwkeurige controle mogelijk is over hoe nummers verschijnen.

Maskers programmatisch toepassen

Om nummers te formatteren met dezelfde maskersyntaxis buiten een veld, bijvoorbeeld bij het weergeven van gegevens in een Table, gebruik de MaskDecorator utility klasse.

Masker karakteren

Karakter	Beschrijving
`0`	Altijd vervangen door een cijfer (0–9).
`#`	Onderdrukt leidende nullen. Vervangen door het opvulkaraakater aan de linkerkant van het decimaalpunt. Voor achterliggende cijfers, vervangen door een spatie of nul. Anders, vervangen door een cijfer.
`,`	Gebruikt als een groeperingsscheidingsteken (bijv. duizenden). Vervangen door het opvulkaraakater als er geen cijfers voorafgaan. Anders, weergegeven als een komma.
`-`	Toont een minteken (`-`) als het nummer negatief is. Vervangen door het opvulkaraakater als positief.
`+`	Toont `+` voor positieve of `-` voor negatieve nummers.
`$`	Resultaat in een dollar teken.
`(`	Voegt een linkse haakje `(` in voor negatieve waarden. Vervangen door het opvulkaraakater als positief.
`)`	Voegt een rechtse haakje `)` in voor negatieve waarden. Vervangen door het opvulkaraakater als positief.
`CR`	Toont `CR` voor negatieve nummers. Toont twee spaties als het nummer positief is.
`DR`	Toont `CR` voor negatieve nummers. Toont `DR` voor positieve nummers.
`*`	Voegt een asterisk `*` in.
`.`	Markeert het decimaal punt. Als er geen cijfers in de uitvoer verschijnen, vervangen door het opvulkaraakater. Na het decimaal, worden opvulkaraakters behandeld als spaties.
`B`	Wordt altijd een spatie. Elke andere letterlijke karakter wordt weergegeven zoals het is.

Sommige van de bovenstaande karakters kunnen meer dan eens in het mask verschijnen voor formatting. Deze omvatten -, +, $, en (. Als een van deze karakters in het mask aanwezig is, wordt de eerste die tegenkomt naar de laatste positie verplaatst waar een # of , door het opvulkaraakater is vervangen. Als er geen dergelijke positie bestaat, blijft het Dubbele karakter waar het is.

Geen Automatische Afronding

Een mask binnen een veld rondt NIET af. Bijvoorbeeld, wanneer een waarde zoals 12.34567 in een veld met het mask ###0.00 wordt geplaatst, krijg je 12.34.

Groep en decimaal scheidingstekens

Het MaskedNumberField ondersteunt aanpassing van groeperings en decimaal karakters, waardoor het gemakkelijk is om nummerformattering aan te passen aan verschillende lokale of zakelijke conventies.

De groepscheiding wordt gebruikt om duizenden visueel te scheiden (bijv. 1,000,000).
De decimaal scheiding geeft het fractionele deel van een nummer aan (bijv. 123.45).

Dit is nuttig in internationale toepassingen waar verschillende regio's verschillende karakters gebruiken (bijv. . vs ,).

field.setGroupCharacter(".");   // bijv. 1.000.000
field.setDecimalCharacter(","); // bijv. 123,45

Standaard Gedrag

Standaard past MaskedNumberField groeps- en decimaal scheidingstekens toe op basis van de huidige lokale van de app. Je kunt ze op elk moment overschrijven met de provided setters.

Negateerbaar

Het MaskedNumberField ondersteunt een optie om te controleren of negatieve nummers zijn toegestaan.

Standaard zijn negatieve waarden zoals -123.45 toegestaan. Om dit te voorkomen, gebruik setNegateable(false) om invoer te beperken tot alleen positieve waarden.

Dit is nuttig in zakelijke scenario's waar waarden zoals hoeveelheden, totalen, of percentages altijd niet-negatief moeten zijn.

field.setNegateable(false);

Wanneer negateable is ingesteld op false, blokkeert het veld elke poging om een minteken in te voeren of anderszins negatieve waarden in te voeren.

Min en max waarden

Het MaskedNumberField ondersteunt het instellen van numerieke grenzen met behulp van setMin() en setMax(). Deze beperkingen helpen om ervoor te zorgen dat de invoer van de gebruiker binnen een geldige, verwachte range blijft.

Minimale Waarde Gebruik setMin() om het laagste acceptabele nummer te definiëren:
```
field.setMin(10.0); // Minimale waarde: 10
```
Als de gebruiker een nummer invoert dat onder deze drempel ligt, wordt het als ongeldig beschouwd.
Maximale Waarde Gebruik setMax() om het hoogste acceptabele nummer te definiëren:
```
field.setMax(100.0); // Maximale waarde: 100
```
Waarden boven deze limiet worden als ongeldig gemarkeerd.

Het waarde herstellen

Het MaskedNumberField ondersteunt een herstelfunctie die de waarde van het veld naar een vooraf gedefinieerde staat reset. Dit kan nuttig zijn wanneer gebruikers wijzigingen moeten ongedaan maken, per ongeluk aangebrachte bewerkingen willen terugdraaien, of willen terugkeren naar een bekende standaardwaarde.

Om een specifieke waarde te herstellen, definieer het gebruik van setRestoreValue(). Wanneer nodig, kan het veld programatisch worden gereset met behulp van restoreValue().

numberField.setRestoreValue(1500.00);
numberField.restoreValue();

Manieren om de waarde te herstellen

Programatisch met restoreValue()
Via toetsenbord, door op ESC te drukken (dit is de standaard hersteltoets tenzij overschreven)

Als er geen herstelwaarde is ingesteld, stellen zowel restoreValue() als ESC de waarde van het veld in op null.