MaskedNumberField

Le MaskedNumberField est un champ de texte conçu pour la saisie numérique structurée. Il garantit que les chiffres sont formatés de manière cohérente en fonction d'un masque défini, ce qui le rend particulièrement utile pour les formulaires financiers, les champs de prix ou toute saisie où la précision et la lisibilité sont importantes.

Ce composant prend en charge le formatage des nombres, la localisation des caractères décimaux / de regroupement et des contraintes de valeur optionnelles telles que des minimums ou des maximums.

Basics

Le MaskedNumberField peut être instancié avec ou sans paramètres. Il prend en charge la définition d'une valeur initiale, d'une étiquette, d'un espace réservé et d'un écouteur d'événements pour réagir aux modifications de valeur.

Cette démo présente un calculateur de pourboire qui utilise le MaskedNumberField pour une saisie numérique intuitive. Un champ est configuré pour accepter un montant de facture formaté, tandis que l'autre saisit un pourcentage de pourboire en nombre entier. Les deux champs appliquent des masques numériques pour garantir un formatage cohérent et prévisible.

Afficher le code

MaskedNumberFieldView.java

Mask rules

Le MaskedNumberField utilise une chaîne de masque pour contrôler la façon dont l'entrée numérique est formatée et affichée. Chaque caractère dans le masque définit un comportement de formatage spécifique, permettant un contrôle précis sur l'apparence des nombres.

Application des masques par programme

Pour formater des nombres avec la même syntaxe de masque en dehors d'un champ, par exemple lors du rendu de données dans un Table, utilisez la classe utilitaire MaskDecorator.

Mask characters

Caractère	Description
`0`	Toujours remplacé par un chiffre (0–9).
`#`	Supprime les zéros initiaux. Remplacé par le caractère de remplissage à gauche du point décimal. Pour les chiffres fins, remplacé par un espace ou un zéro. Sinon, remplacé par un chiffre.
`,`	Utilisé comme séparateur de regroupement (par exemple, milliers). Remplacé par le caractère de remplissage si aucun chiffre ne le précède. Sinon, affiché comme une virgule.
`-`	Affiche un signe moins (`-`) si le nombre est négatif. Remplacé par le caractère de remplissage si positif.
`+`	Affiche `+` pour les nombres positifs ou `-` pour les nombres négatifs.
`$`	Résulte toujours par un signe dollar.
`(`	Insère une parenthèse gauche `(` pour les valeurs négatives. Remplacé par le caractère de remplissage si positif.
`)`	Insère une parenthèse droite `)` pour les valeurs négatives. Remplacé par le caractère de remplissage si positif.
`CR`	Affiche `CR` pour les nombres négatifs. Affiche deux espaces si le nombre est positif.
`DR`	Affiche `CR` pour les nombres négatifs. Affiche `DR` pour les nombres positifs.
`*`	Insère un astérisque `*`.
`.`	Marque le point décimal. Si aucun chiffre n'apparaît dans la sortie, remplacé par le caractère de remplissage. Après le décimal, les caractères de remplissage sont traités comme des espaces.
`B`	Devenant toujours un espace. Tout autre caractère littéral est affiché tel quel.

Certains des caractères ci-dessus peuvent apparaître plus d'une fois dans le masque pour le formatage. Ceux-ci incluent -, +, $, et (. Si l'un de ces caractères est présent dans le masque, le premier rencontré sera déplacé à la dernière position où un # ou , a été remplacé par le caractère de remplissage. Si aucune position de ce type n'existe, le caractère double reste à sa place.

Pas de Rounding Automatique

Un masque dans un champ ne fait PAS de rounding. Par exemple, lorsque vous placez une valeur telle que 12.34567 dans un champ masqué avec ###0.00, vous obtiendrez 12.34.

Group and decimal separators

Le MaskedNumberField prend en charge la personnalisation des caractères de regroupement et décimaux, facilitant ainsi l'adaptation du formatage des nombres à différentes conventions locales ou commerciales.

Le séparateur de groupe est utilisé pour séparer visuellement les milliers (par exemple, 1,000,000).
Le séparateur décimal indique la partie fractionnaire d'un nombre (par exemple, 123.45).

Ceci est utile dans les applications internationales où différentes régions utilisent des caractères différents (par exemple, . contre ,).

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

Comportement par défaut

Par défaut, le MaskedNumberField applique des séparateurs de groupe et décimaux en fonction de la locale actuelle de l'application. Vous pouvez les remplacer à tout moment en utilisant les setters fournis.

Negateable

Le MaskedNumberField prend en charge une option pour contrôler si les nombres négatifs sont autorisés.

Par défaut, les valeurs négatives comme -123.45 sont autorisées. Pour empêcher cela, utilisez setNegateable(false) pour restreindre l'entrée uniquement aux valeurs positives.

Cela est utile dans les scénarios commerciaux où des valeurs telles que des quantités, des totaux ou des pourcentages doivent toujours être non négatifs.

field.setNegateable(false);

Lorsque negateable est défini sur false, le champ bloque toute tentative d'entrer un signe moins ou d'autres valeurs négatives.

Afficher le code

MaskedNumNegatableView.java

Min and max values

Le MaskedNumberField prend en charge la définition de limites numériques à l'aide de setMin() et setMax(). Ces contraintes aident à garantir que l'entrée utilisateur reste dans une plage valide et attendue.

Valeur Min Utilisez setMin() pour définir le plus bas nombre acceptable :
```
field.setMin(10.0); // Valeur minimum : 10
```
Si l'utilisateur saisit un nombre en dessous de ce seuil, il sera considéré comme invalide.
Valeur Max Utilisez setMax() pour définir le plus haut nombre acceptable :
```
field.setMax(100.0); // Valeur maximum : 100
```
Les valeurs au-dessus de cette limite seront signalées comme invalides.

Restoring the value

Le MaskedNumberField prend en charge une fonction de restauration qui réinitialise la valeur du champ à un état prédéfini. Cela peut être utile lorsque les utilisateurs doivent annuler des changements, revenir sur des modifications accidentelles ou retourner à une valeur par défaut connue.

Pour activer ce comportement, définissez la valeur cible à l'aide de setRestoreValue(). Lorsque cela est nécessaire, le champ peut être réinitialisé par programme à l'aide de restoreValue().

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

Ways to restore the value

Par programme en utilisant restoreValue()
Via le clavier, en appuyant sur ESC (c'est la touche de restauration par défaut, sauf si elle est remplacée)

La valeur de restauration doit être définie explicitement. Si elle n'est pas définie, la fonction ne rétablira pas le champ.

Afficher le code

MaskedNumRestoreView.java