MaskedTextField

MaskedTextField 组件提供了一种可配置的文本输入，强制执行格式规则和验证。它非常适合需要结构化输入的应用，例如金融、电子商务和医疗系统。

这个组件可以在有参数或无参数的情况下实例化。您可以定义初始值、标签、占位符文本以及在值更改时的监听器。

MaskedTextField field = new MaskedTextField("账户 ID");
field.setMask("ZZZZ-0000")
  .setHelperText("掩码: ZZZZ-0000 - 例如: SAVE-2025")

掩码规则

MaskedTextField 使用掩码格式化文本输入——一个字符串，定义每个位置上允许的字符。这确保了诸如电话号码、邮政编码和身份证格式等输入的一致性和结构性。

以编程方式应用掩码

要在字段外部使用相同的掩码语法格式化字符串，例如在 Table 中呈现数据时，请使用 MaskDecorator 实用程序类。

支持的掩码字符

字符	描述
`X`	任何可打印字符
`a`	任何字母字符（大写或小写）
`A`	任何字母字符；小写字母会被转换为大写
`0`	任何数字（0–9）
`z`	任何数字或字母（大写或小写）
`Z`	任何数字或字母；小写字母会被转换为大写

掩码中的所有其他字符都被视为字面量，必须准确输入。例如，像 XX@XX 的掩码要求用户在中间输入 @。

无效字符 将被静默忽略。
短输入 用空格填充。
长输入 被截断以适应掩码。

示例

field.setMask("(000) 000-0000");     // 示例: (123) 456-7890
field.setMask("A00 000");            // 示例: A1B 2C3 (加拿大邮政编码)
field.setMask("ZZZZ-0000");          // 示例: ABCD-1234
field.setMask("0000-0000-0000-0000");// 示例: 1234-5678-9012-3456

允许全输入

如果掩码仅包含 X，则字段的行为类似于标准的 TextField，允许任何可打印输入。当您希望保留格式化能力而不应用严格的字符规则时，这很有用。

显示代码

MaskedTextFieldView.java

验证模式

虽然掩码定义了输入的结构，但您可以将它们与验证模式结合使用，以强制执行更具体的输入规则。这为使用正则表达式的客户端验证添加了额外的层次。

使用 setPattern() 方法应用自定义正则表达式：

field.setPattern("[A-Za-z0-9]{10}"); // 强制 10 个字符的字母数字代码

这确保输入不仅符合掩码，还符合定义的结构，例如长度或允许的字符。

这在以下情况下尤其有用：

掩码允许过多的灵活性
您希望强制执行确切的长度或特定格式（例如十六进制、Base64、UUID）

正则表达式格式

模式必须是有效的 JavaScript 正则表达式，由 RegExp 类型使用。您可以在 HTML 模式属性文档中找到更多详细信息。

恢复值

MaskedTextField 包含恢复功能，可以将字段的值重置为预定义或原始状态。这对于撤销用户更改或恢复到默认输入非常有用。

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

恢复值的方法

以编程方式，通过调用 restoreValue()
通过键盘，按 ESC（这是默认的恢复键，除非被事件监听器覆盖）

您可以使用 setRestoreValue() 设置要恢复的值。如果未设置恢复值，字段将恢复为渲染时的初始值。

显示代码

MaskedTextFieldRestoreView.java