MaskedTimeField

MaskedTimeField 是一个文本输入框，允许用户以数字形式输入时间，并在字段失去焦点时根据定义的掩码自动格式化输入。掩码指定了期望的时间格式，以指导输入和显示。该组件支持灵活的解析、验证、本地化和数值恢复，以便于一致的时间处理。

寻找日期输入？

MaskedTimeField 专为 仅时间 输入而构建。如果您需要处理日期的组件，并具有类似的基于掩码的格式，请查看 MaskedDateField。

MaskedTimeField 可以在有或没有参数的情况下实例化。您可以定义初始值、标签、占位符和用于值更改的事件监听器。

掩码规则

MaskedTimeField 使用格式指示符来定义时间的解析和显示方式。每个格式指示符以 % 开头，后跟一个表示时间组件的字母。

以编程方式应用掩码

要在字段之外使用相同的掩码语法格式化或解析时间，请使用 MaskDecorator 实用类。

时间格式指示符

格式	描述
`%H`	小时（24小时制）
`%h`	小时（12小时制）
`%m`	分钟
`%s`	秒钟
`%p`	上午/下午

修饰符

修饰符细化时间组件的显示：

修饰符	描述
`z`	零填充
`s`	简短文本表示
`l`	长文本表示
`p`	压缩数字
`d`	十进制（默认格式）

这些允许灵活且符合地方特色的时间格式化。

时间格式本地化

MaskedTimeField 通过设置适当的区域设置支持本地化。这确保时间输入和输出符合区域惯例。

field.setLocale(Locale.GERMANY);

这会影响上午/下午指示符的显示方式、分隔符的处理方式以及数值的解析方式。

解析逻辑

MaskedTimeField 根据定义的时间掩码解析用户输入。它接受完整和简略的数字输入，并可有或没有分隔符，从而允许灵活输入，同时确保有效的时间。解析行为取决于掩码定义的格式顺序（例如，%Hz:%mz 用于小时/分钟）。此格式确定数字序列的解释方式。

示例解析场景

输入	掩码	解释为
`900`	`%Hz:%mz`	`09:00`
`1345`	`%Hz:%mz`	`13:45`
`0230`	`%hz:%mz %p`	`02:30 AM`
`1830`	`%hz:%mz %p`	`06:30 PM`

设置最小/最大约束

您可以使用 setMin() 和 setMax() 方法限制 MaskedTimeField 中允许的时间范围：

field.setMin(LocalTime.of(8, 0));
field.setMax(LocalTime.of(18, 0));

这两个方法接受类型为 java.time.LocalTime 的值。超出定义范围的输入将被视为无效。

恢复值

MaskedTimeField 包含一个还原功能，可以将字段的值重置为预定义或原始状态。这在撤消更改或恢复到默认时间时非常有用。

field.setRestoreValue(LocalTime.of(12, 0));
field.restoreValue();

恢复值的方法

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

验证模式

您可以使用 setPattern() 方法应用客户端验证规则，使用正则表达式：

field.setPattern("^\\d{2}:\\d{2}$");

此模式确保仅与 HH:mm 格式（两个数字，冒号，两个数字）匹配的值被视为有效。

正则表达式格式

该模式必须遵循 JavaScript 正则表达式语法，详细文档可以参见这里。

输入处理说明

该字段尝试基于当前掩码解析和格式化数字时间输入。然而，用户仍然可以手动输入不匹配预期格式的值。如果输入在语法上有效但在语义上不正确或不可解析（例如 99:99），它可能会通过模式检查但在逻辑验证中失败。即使设置了正则表达式模式，您仍然应该在应用逻辑中验证输入值，以确保时间不仅格式正确而且有意义。

时间选择器

MaskedTimeField 包含一个内置的时间选择器，允许用户可视化选择时间，而不是键入输入。这提高了对不太技术用户的可用性，或在需要精确输入的情况下。

访问选择器

您可以使用 getPicker() 访问时间选择器：

TimePicker picker = field.getPicker();

显示/隐藏选择器图标

使用 setIconVisible() 显示或隐藏字段旁的时钟图标：

picker.setIconVisible(true); // 显示图标

自动打开行为

您可以配置选择器在用户与字段交互时（例如点击、按下 Enter 或箭头键）自动打开：

picker.setAutoOpen(true);

通过选择器强制选择

为了确保用户只能使用选择器选择时间（而不是手动输入），请结合以下两个设置：

field.getPicker().setAutoOpen(true); // 用户交互时打开选择器
field.setAllowCustomValue(false);    // 禁用手动文本输入

此设置确保所有时间输入通过选择器 UI 进行，这在需要严格格式控制和消除输入解析问题时非常有用。

手动打开选择器

要以编程方式打开时间选择器：

picker.open();

或使用别名：

picker.show(); // 与 open() 相同

设置选择器步长

您可以使用 setStep() 定义选择器中可选择时间之间的间隔。这允许您控制时间选项的粒度——非常适合于分段如 15 分钟的调度场景。

field.getPicker().setStep(Duration.ofMinutes(15));

步长约束

步长必须均匀划分一个小时或一天。否则，将抛出异常。

这确保下拉列表包含可预测、均匀间隔的值，如 09:00、09:15、09:30 等。