MaskedTextField

MaskedTextField 组件旨在提供可配置且易于验证的文本输入。它非常适合需要格式化输入的应用程序，例如金融、电子商务和医疗应用。

基本知识

MaskedTextField 可以根据需要进行初始化，可以包含也可以不包含参数。您可以定义初始值、标签、占位符文本以及在值发生更改时的监听器。

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

掩码规则

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

支持的掩码字符

字符	描述
`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，允许任何可打印的输入。这在您想保留格式化的能力而不应用严格的字符规则时非常有用。

显示代码

Java

验证模式

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

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

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

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

这在以下情况下特别有用：

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

正则表达式格式

模式必须是有效的 JavaScript 正则表达式，如 RegExp 类型所使用的那样。您可以在 HTML 模式属性文档中找到更多细节。

恢复值

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

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

恢复值的方法

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

您可以通过 setRestoreValue() 设置要恢复的值。如果未设置恢复值，字段将在渲染时恢复到初始值。

显示代码

Java