MaskedNumberField

Das MaskedNumberField ist ein Texteingabefeld, das zum einheitlichen Formatieren numerischer Eingaben basierend auf einer definierten Maske entwickelt wurde. Es ist nützlich für Finanzformulare, Preisfelder oder jede Eingabe, bei der Präzision und Lesbarkeit wichtig sind.

Diese Komponente kann mit oder ohne Parameter instanziiert werden. Sie unterstützt die Zahlenformatierung, die Lokalisierung von Dezimal-/Gruppierungszeichen und optionale Wertbeschränkungen wie Mindest- oder Höchstwerte. Sie unterstützt auch das Festlegen eines Anfangswerts, eines Labels, eines Platzhalters und eines Ereignislisteners, um auf Wertänderungen zu reagieren.

Das folgende Beispiel zeigt einen Tip Calculator, der MaskedNumberField für eine intuitive numerische Eingabe verwendet. Ein Feld ist so konfiguriert, dass es einen formatierten Rechnungsbetrag akzeptiert, während das andere einen ganzzahligen Trinkgeldprozentsatz erfasst.

Code anzeigen

MaskedNumberFieldView.java

Maskenregeln

Das MaskedNumberField verwendet eine Maskenzeichenfolge, um zu steuern, wie numerische Eingaben formatiert und angezeigt werden. Jedes Zeichen in der Maske definiert ein bestimmtes Formatverhalten, das eine präzise Kontrolle darüber ermöglicht, wie Zahlen dargestellt werden.

Masken programmatisch anwenden

Um Zahlen mit derselben Maskensyntax außerhalb eines Feldes zu formatieren, beispielsweise beim Rendern von Daten in einer Table, verwenden Sie die Dienstprogrammklasse MaskDecorator.

Maskenzeichen

Zeichen	Beschreibung
`0`	Wird immer durch eine Ziffer (0–9) ersetzt.
`#`	Unterdrückt führende Nullen. Wird durch das Füllzeichen links vom Dezimalpunkt ersetzt. Für nachfolgende Ziffern wird es durch ein Leerzeichen oder Null ersetzt. Andernfalls wird es durch eine Ziffer ersetzt.
`,`	Wird als Gruppierungszeichen (z.B. für Tausender) verwendet. Wird durch das Füllzeichen ersetzt, wenn keine Ziffern davor stehen. Andernfalls wird es als Komma angezeigt.
`-`	Zeigt ein Minuszeichen (`-`) an, wenn die Zahl negativ ist. Wird durch das Füllzeichen ersetzt, wenn sie positiv ist.
`+`	Zeigt `+` für positive oder `-` für negative Zahlen an.
`$`	Führt immer zu einem Dollarzeichen.
`(`	Fügt eine linke Klammer `(` für negative Werte ein. Wird durch das Füllzeichen ersetzt, wenn sie positiv sind.
`)`	Fügt eine rechte Klammer `)` für negative Werte ein. Wird durch das Füllzeichen ersetzt, wenn sie positiv sind.
`CR`	Zeigt `CR` für negative Zahlen an. Zeigt zwei Leerzeichen an, wenn die Zahl positiv ist.
`DR`	Zeigt `CR` für negative Zahlen an. Zeigt `DR` für positive Zahlen an.
`*`	Fügt einen Asterisk `*` ein.
`.`	Kennzeichnet den Dezimalpunkt. Wenn keine Ziffern in der Ausgabe erscheinen, wird es durch das Füllzeichen ersetzt. Nach dem Dezimalpunkt werden Füllzeichen als Leerzeichen behandelt.
`B`	Wird immer zu einem Leerzeichen. Jedes andere literale Zeichen wird unverändert angezeigt.

Einige der oben genannten Zeichen können mehr als einmal in der Maske erscheinen, um das Format zu steuern. Dazu gehören -, +, $ und (. Wenn eines dieser Zeichen in der Maske vorhanden ist, wird das erste Zeichen, das gefunden wird, an die letzte Position verschoben, an der ein # oder , durch das Füllzeichen ersetzt wurde. Wenn keine solche Position existiert, bleibt das doppelte Zeichen an seinem Platz.

Keine automatische Rundung

Eine Maske innerhalb eines Feldes rundet NICHT. Wenn Sie beispielsweise einen Wert wie 12.34567 in ein mit ###0.00 maskiertes Feld eingeben, erhalten Sie 12.34.

Gruppen- und Dezimalseparatoren

Das MaskedNumberField unterstützt die Anpassung von Gruppierungs- und Dezimalzeichen, was es einfach macht, die Zahlenformatierung an verschiedene Regionen oder Geschäftspraktiken anzupassen.

Der Gruppierungsseparator wird verwendet, um Tausender visuell zu trennen (z.B. 1.000.000).
Der Dezimalseparator zeigt den Bruchteil einer Zahl an (z.B. 123.45).

Dies ist nützlich in internationalen Anwendungen, in denen verschiedene Regionen unterschiedliche Zeichen verwenden (z.B. . vs ,).

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

Standardverhalten

Standardmäßig wendet MaskedNumberField Gruppierungs- und Dezimalseparatoren basierend auf der aktuellen Sprache des Apps an. Sie können diese jederzeit mit den bereitgestellten Settern überschreiben.

Negierbar

Das MaskedNumberField unterstützt eine Option zur Steuerung, ob negative Zahlen zulässig sind.

Standardmäßig sind negative Werte wie -123.45 zulässig. Um dies zu verhindern, verwenden Sie setNegateable(false), um die Eingabe auf positive Werte zu beschränken.

Dies ist nützlich in Geschäftsszenarien, in denen Werte wie Mengen, Summen oder Prozentsätze immer nicht negativ sein müssen.

field.setNegateable(false);

Wenn negatable auf false gesetzt ist, blockiert das Feld alle Versuche, ein Minuszeichen einzugeben oder andere negative Werte einzugeben.

Code anzeigen

MaskedNumNegatableView.java

Mindest- und Höchstwerte

Das MaskedNumberField unterstützt das Festlegen numerischer Grenzen mithilfe von setMin() und setMax(). Diese Einschränkungen helfen sicherzustellen, dass die Benutzereingaben innerhalb eines gültigen, erwarteten Bereichs bleiben.

Mindestwert Verwenden Sie setMin(), um die niedrigste akzeptable Zahl zu definieren:
```
field.setMin(10.0); // Mindestwert: 10
```
Wenn der Benutzer eine Zahl unter diesem Schwellenwert eingibt, wird sie als ungültig angesehen.
Höchstwert Verwenden Sie setMax(), um die höchste akzeptable Zahl zu definieren:
```
field.setMax(100.0); // Höchstwert: 100
```
Werte über diesem Limit werden als ungültig markiert.

Wiederherstellung des Wertes

Das MaskedNumberField unterstützt eine Wiederherstellungsfunktion, die den Wert des Feldes auf einen vordefinierten Zustand zurücksetzt. Dies kann nützlich sein, wenn Benutzer Änderungen rückgängig machen, versehentliche Bearbeitungen zurücksetzen oder zu einem bekannten Standardwert zurückkehren müssen.

Um dieses Verhalten zu aktivieren, definieren Sie den Zielwert mit setRestoreValue(). Bei Bedarf kann das Feld programmgesteuert mit restoreValue() zurückgesetzt werden.

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

Möglichkeiten zur Wiederherstellung des Wertes

Programmgesteuert mit restoreValue()
Über die Tastatur, indem die Taste ESC gedrückt wird (dies ist die Standardwiederherstelltaste, es sei denn, sie wird überschrieben)

Der Wiederherstellungswert muss ausdrücklich festgelegt werden. Wenn er nicht definiert ist, wird die Funktion das Feld nicht zurücksetzen.

Code anzeigen

MaskedNumRestoreView.java