MaskedDateField

MaskedDateField 是一个用于结构化日期输入的文本输入控件。它允许用户作为数字输入日期，并在字段失去焦点时基于定义的掩码自动格式化输入。掩码是一个字符串，指定预期的日期格式，指导输入和显示。

此组件支持灵活的解析、验证、本地化和值恢复。它特别适用于像注册、预订和调度这样的表单，要求一致且地域特定的日期格式。

寻找时间输入？

MaskedDateField专注于日期值。如果您需要一个类似的组件来输入和格式化时间，请查看MaskedTimeField。

基础

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

显示代码

Java

掩码规则

MaskedDateField 支持全球多种日期格式，这些格式因日、月、年的顺序而异。常见模式包括：

日/月/年（在大多数欧洲地区使用）
月/日/年（在美国使用）
年/月/日（在中国、日本和韩国使用；也是ISO标准：YYYY-MM-DD）

在这些格式中，地方变体包括分隔符的选择（例如，-、/或.）、年份是两位数还是四位数以及单个数字月份或日期是否用前导零填充。

为了处理这种多样性，MaskedDateField 使用格式指示符，每个指示符以%开头，后跟一个表示日期特定部分的字母。这些指示符定义了如何解析输入以及如何显示日期。

日期格式指示符

格式	描述
`%Y`	年
`%M`	月
`%D`	日

修饰符

修饰符允许更好地控制日期组成部分的格式：

修饰符	描述
`z`	零填充
`s`	短文本表示
`l`	长文本表示
`p`	紧凑数字
`d`	小数（默认格式）

这些可以组合起来构建各种类型的日期掩码。

日期格式本地化

MaskedDateField 通过设置适当的区域设置来适应区域日期格式。这确保日期以匹配用户期望的方式显示和解析。

区域	格式	示例
美国	MM/DD/YYYY	`07/04/2023`
欧洲	DD/MM/YYYY	`04/07/2023`
ISO标准	YYYY-MM-DD	`2023-07-04`

要应用本地化，请使用setLocale()方法。此方法接受一个java.util.Locale，并自动调整格式和解析：

dateField.setLocale(Locale.FRANCE);

解析逻辑

MaskedDateField 根据定义的日期掩码解析用户输入。它接受完整和简写的数字输入，带或不带分隔符，允许灵活输入，同时确保有效日期。解析行为取决于掩码定义的格式顺序（例如，%Mz/%Dz/%Yz 为月份/日期/年份）。这个格式决定了数字序列的解释方式。

例如，假设今天是2012年9月15日，以下是不同输入的解析示例：

示例解析场景

输入	YMD（ISO）	MDY（美国）	DMY（欧洲）
`1`	单个数字总是被解析为当前月份的日期，所以这将是2012年9月1日。	同YMD	同YMD
`12`	两个数字总是被解析为当前月份的日期，所以这将是2012年9月12日。	同YMD	同YMD
`112`	三个数字被解析为1位数字的月份和2位数字的日期，所以这将是2012年1月12日。	同YMD	三个数字被解析为1位数字的日期和2位数字的月份，所以这将是2012年12月1日。
`1004`	四个数字被解析为MMDD，所以这将是2012年10月4日。	同YMD	四个数字被解析为DDMM，所以这将是2012年4月10日。
`020304`	六个数字被解析为YYMMDD，所以这将是2002年3月4日。	六个数字被解析为MMDDYY，所以这将是2004年2月3日。	六个数字被解析为DDMMYY，所以这将是2004年3月2日。
`8 digits`	八个数字被解析为YYYYMMDD。例如，`20040612` 是 2004年6月12日。	八个数字被解析为MMDDYYYY。例如，`06122004` 是 2004年6月12日。	八个数字被解析为DDMMYYYY。例如，`06122004` 是 2004年12月6日。
`12/6`	用任何有效分隔符分隔的两个数字被解析为MM/DD，所以这将是2012年12月6日。注意：除了字母和数字外，所有字符都被视为有效分隔符。	同YMD	用任何分隔符分隔的两个数字被解析为DD/MM，所以这将是2012年6月12日。
`3/4/5`	2012年4月5日	2005年3月4日	2005年4月3日

设置最小/最大约束

您可以使用setMin()和setMax()方法限制MaskedDateField中允许的日期范围：

dateField.setMin(LocalDate.of(2020, 1, 1));
dateField.setMax(LocalDate.of(2030, 12, 31));

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

恢复值

MaskedDateField 包含一个恢复功能，用于将字段的值重置为预定义或原始状态。这对于还原用户输入或重置为默认日期非常有用。

dateField.setRestoreValue(LocalDate.of(2025, 1, 1));
dateField.restoreValue();

恢复值的方式

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

您可以使用 setRestoreValue() 设置要恢复的值，传递一个 LocalDate 实例。

显示代码

Java

验证模式

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

dateField.setPattern("^\\d{2}/\\d{2}/\\d{4}$");

此模式确保只有与 MM/DD/YYYY 格式（两位数，斜杠，两位数，斜杠，四位数）匹配的值被视为有效。

正则表达式格式

模式必须遵循 JavaScript RegExp 语法，如文档中所述 here。

输入处理的注意事项

该字段尝试根据当前掩码解析和格式化数字日期输入。然而，用户仍然可以手动输入不符合预期格式的值。如果输入在语法上有效但在语义上不正确或无法解析（例如 99/99/9999），则可能会通过模式检查但未能通过逻辑验证。即使设置了正则表达式模式，您也应该始终在应用逻辑中验证输入值，以确保日期格式正确且有意义。

日期选择器

MaskedDateField 包含一个内置的日历选择器，允许用户以视觉方式选择日期，而不是输入。这增强了不太技术化用户的可用性，或在需要精确输入时。

显示代码

Java

访问选择器

您可以使用 getPicker() 访问日期选择器：

DatePicker picker = dateField.getPicker();

显示/隐藏选择器图标

使用 setIconVisible() 显示或隐藏字段旁边的日历图标：

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

自动打开行为

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

picker.setAutoOpen(true);

仅通过选择器强制选择

为确保用户只能通过日历选择器选择日期（而不能手动输入），请结合以下两个设置：

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

这种设置保证所有日期输入都来自选择器用户界面，当您希望严格格式控制并消除由输入引起的解析问题时非常有用。

手动打开日历

要以编程方式打开日历：

picker.open();

或使用别名：

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

在日历中显示周数

选择器可以选择性地在日历视图中显示周数：

picker.setShowWeeks(true);