MaskedNumberField

MaskedNumberField 是一个用于结构化数字输入的文本输入。它确保基于定义的掩码一致地格式化数字，对于财务表单、定价字段或任何需要精确度和可读性的输入特别有用。

此组件支持数字格式化、小数/分组字符的本地化，以及诸如最小值或最大值之类的可选值约束。

基础

MaskedNumberField 可以实例化时带参数或不带参数。它支持设置初始值、标签、占位符和侦听器以响应值的变化。

此演示展示了一个小费计算器，使用 MaskedNumberField 进行直观的数字输入。一个字段配置为接受格式化的账单金额，而另一个字段则捕获整数小费百分比。两个字段应用数字掩码，以确保格式一致且可预测。

显示代码

Java

掩码规则

MaskedNumberField 使用掩码字符串来控制数字输入的格式和显示。掩码中的每个字符定义了特定的格式化行为，使数字的外观得以精确控制。

掩码字符

字符	描述
`0`	始终被数字（0–9）替换。
`#`	抑制前导零。用小数点左侧的填充字符替换。对于尾随数字，用空格或零替换。否则，用数字替换。
`,`	用作分组分隔符（例如千位）。如果没有数字在前，则用填充字符替换。否则，显示为逗号。
`-`	如果数字是负数，则显示负号（`-`）。如果是正数，则用填充字符替换。
`+`	对于正数显示`+`，对于负数显示`-`。
`$`	始终显示美元符号。
`(`	对于负值插入左括号`(`。如果是正数，则用填充字符替换。
`)`	对于负值插入右括号`)`。如果是正数，则用填充字符替换。
`CR`	对于负数显示`CR`。如果数字是正数，则显示两个空格。
`DR`	对于负数显示`CR`。对于正数显示`DR`。
`*`	插入星号`*`。
`.`	标记小数点。如果输出中没有数字，则用填充字符替换。在小数之后，填充字符被视为空间。
`B`	始终变为空格。任何其他字面字符原样显示。

上述某些字符可以在掩码中出现多次用于格式化。这些字符包括-、+、$和(。如果在掩码中存在任何这些字符，则遇到的第一个字符将移到最后一个#或,被填充字符替换的位置。如果不存在这样的位，则双字符将保留在原处。

无自动舍入

字段中的掩码不进行舍入。例如，将值12.34567放入掩码为###0.00的字段中，你将得到12.34。

分组和小数分隔符

MaskedNumberField 支持自定义分组和小数字符，使数字格式适应不同的地区或商业惯例变得容易。

分组分隔符 用于直观地分隔千位（例如 1,000,000）。
小数分隔符 指示一个数字的分数部分（例如 123.45）。

在国际应用程序中，这对于不同地区使用不同字符（例如 . 与 ,）非常有用。

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

默认行为

默认情况下，MaskedNumberField 根据应用程序当前的区域设置应用分组和小数分隔符。你可以随时使用提供的设置器覆盖它们。

可否为负数

MaskedNumberField 支持选项，以控制是否允许负数。

默认情况下，允许负值如 -123.45。要阻止这一点，请使用 setNegateable(false) 限制输入仅为正值。

在业务场景中，数量、总计或百分比等值必须始终为非负值。

field.setNegateable(false);

当 negatable 设置为 false 时，该字段阻止任何输入负号或其他输入负值的尝试。

显示代码

Java

最小值和最大值

MaskedNumberField 支持使用 setMin() 和 setMax() 设置数值边界。这些约束帮助确保用户输入保持在有效、预期的范围内。

最小值
使用 setMin() 定义最低可接受的数字：
```
field.setMin(10.0); // 最小值: 10
```
如果用户输入的数字低于此阈值，则将被视为无效。
最大值
使用 setMax() 定义最高可接受的数字：
```
field.setMax(100.0); // 最大值: 100
```
超过此限制的值将被标记为无效。

恢复值

MaskedNumberField 支持一个恢复功能，将字段的值重置为预定义状态。当用户需要撤消更改、恢复意外编辑或返回到已知默认值时，这非常有用。

要启用此行为，请使用 setRestoreValue() 定义目标值。在需要时，可以使用 restoreValue() 程序性地重置字段。

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

恢复值的方法

程序性地 使用 restoreValue()
通过键盘，按 ESC（这是默认恢复键，除非被覆盖）

恢复值必须显式设置。如果未定义，则该功能将不会还原字段。

显示代码

Java