• 基本示例
• 模式
  • 双重输入
  • 仅选择器
• 日期格式
  • 样式化格式
  • 令牌格式
• 面板顺序
  • 选择时间
• 值
  • 日期样式
  • 格式化令牌
  • 设置值（填充）
  • 值区域设置
• 时区
  • 案例研究
  • 不确定时区
  • 指定时区
• 禁用日期
  • 最小日期
  • 最大日期
  • 禁用的天数
  • 扫描可用性
• 可清除
• 属性 & 参数
• 部分
  • 覆盖层
  • 年份面板
  • 月份面板
  • 日面板
  • 时间面板
  • 部分关键词
• 可访问性
  • 键盘交互

基本示例

datepicker 输入允许用户从可定制的日历中选择日期，并且可以直接在输入框中输入日期，完全支持国际化。

模式

FormKit 使用独特的掩码解决方案，允许用户通过键入日期到日期选择器输入框（同时限制可用选项仅为有效值）或通过日历输入选择他们的日期。

双重输入

• 文本输入 - 默认情况下，用户可以点击或者用 Tab 键进入显示日期的任何“部分”（月、日、年等）并输入他们想要的值。匹配的值将显示自动完成。除了键入，用户还可以使用上/下箭头键来循环浏览每个部分的可用选项。
• 选择器输入 - 通过点击输入框右侧的“日历”图标，用户还可以显示一个日历弹出窗口来视觉上选择他们的日期：

仅选择器

你可以禁用文本输入机制，并确保某人使用日期选择器对话框来输入他们的日期，通过添加 picker-only 属性。在 picker-only 模式下，点击输入框将立即打开对话框。此外，使用 overlay 对于占位符支持并不是必需的：

日期格式

日期选择器支持 Intl.DateTimeFormat 的“样式化日期”，以及基于令牌的日期格式。要更改显示给用户的格式，请修改 format 属性。

样式化格式

如果您的受众是国际性的，您应该考虑坚持使用“样式化日期”，因为它们是每个地区最自然的日期格式。日期选择器的默认格式是 long。

format 属性可以接受像 long 或 medium 这样的简单字符串，在这种情况下，它使用相应的 Intl.DateTimeFormat dateStyle。或者，您可以提供一个具有 date 和 time 属性及其各自的 Intl.DateTimeFormat 样式的对象（{ date: 'long', time: 'short' }）。

日期样式

使用 format 属性启用以下任何日期样式：

格式样式	示例
full	Wednesday, March 1, 2023, Mercoledì 1 marzo 2023
long	March 1, 2023, 1 marzo 2023
medium	Mar 6, 2023, 6 mar 2023
short	3/1/23, 1/3/23

时间样式

格式样式	示例
long	7:05:00 PM, 19:05:00
medium	7:05:00 PM, 19:05:00
short	7:05 PM, 19:05

令牌格式

您可以使用 format 属性来明确设置一个令牌化的日期格式。令牌格式由一个字符串表示，其中包含任意字符和下表中的一个或多个字符串。

FormKit 与 Intl.DateTimeFormat 接口，根据当前的 locale 自动国际化令牌。例如，对于 2000-01-01，令牌 MMMM 将为 en 地区产生 January，但为 zh 地区产生 一月。

令牌	示例	描述
YY	99, 23, 00	2位数年份
YYYY	1999, 2023, 2100	4位数年份
M	1, 12	月份 1-12
MM	01, 12	月份 01-12
MMM	Jan, Feb	简称 1月-12月
MMMM	January, February	全称 1月 - 12月
D	1, 9, 22	月份中的日 1-31
DD	01, 09, 22	月份中的日 01-31
d	M, T, W, T, F, S, S	单位数日 "T"
ddd	Thu, Sat	简称星期 "Thu"
dddd	Monday, Tuesday	全称星期 "Wednesday"
H	0, 13, 23	最小小时位数，24小时制，0-23
HH	00, 13, 23	2小时位数，24小时制，00-23
h	12, 1, 11	最小小时位数，12小时制，1-12
hh	12, 01, 11	2小时位数，12小时制，01-12
m	1, 59	分钟 0-59
mm	01, 59	分钟 00-59
s	1, 59	秒 0-59
ss	01, 59	秒 00-59
a	am, pm	上午/下午
A	AM, PM	上午/下午

转义标记

要在格式中包含本身就是标记的字母（如 a），您可以在该字符前加上反斜杠 \ 来转义这些标记：

面板顺序

日期选择器的日历弹出窗口有四个“面板”：

• day — 显示一个传统的日历视图，可以选择一个月中的每一天。
• month — 显示一年中的12个月份。
• year — 一次显示十年的年份。
• time — 显示一天中的时间。

当用户打开日期选择器的弹出窗口时，他们将看到一个或多个这些面板。您可以通过提供 sequence 属性来修改显示给用户的面板以及这些面板应该显示的顺序。默认的 sequence 值是 ['day']（这允许您导航到 month 和 year 面板）。

例如，在选择生日时，自然是先选择出生年份，然后是月份，然后是日期。sequence 属性允许这种行为：

选择时间

time 面板可以用来允许用户选择一天中的特定时间。如果您选择了包含时间的 format（如 YYYY-MM-DD HH:mm），您可能会希望将 time 面板包含在您的顺序中：

值

与所有输入一样，日期选择器的 value 既是日期选择器产生的内容，也是读回到日期选择器中进行填充的内容。默认情况下，值的格式是一个 UTC 标准化的 ISO8601 字符串（例如：2014-11-27T03:59:00.000Z）。然而，这种格式可以通过使用 value-format 属性更改为任何受支持的日期样式或上面列出的标记格式。

一个合理的问题是，为什么不总是使用 ISO8601？尽管它是处理日期的最流行方式 — 它对机器和人都可读 — 但它并不是非常适合人类阅读。例如，如果您的表单向餐饮业务发送联系请求电子邮件，那么 ISO8601 可能不是最佳选择。

日期样式

要将日期样式作为值使用，只需将您想要使用的样式传递给 value-format 属性：

格式化令牌

值也可以通过使用格式化令牌以任意格式表示：

设置值（填充）

传递给日期选择器的值必须：

1. 与当前 value-locale 中的 value-format 相匹配，或者
2. 是一个原生的 JavaScript Date 对象。

尽管原生的 Date 对象始终被接受为日期选择器的有效输入，但它们将立即转换为指定的 value-format。

匹配 value-format

使用原生 Date

值区域设置

由于需要使用创建它的同一区域设置来解析值的格式，建议在定义自定义 value-format 时始终指定 value-locale。这确保了无论用户输入日期的区域设置是什么，值都将保持一致：

时区

在任何软件环境中，尤其是基于浏览器的 JavaScript 中，时间都是一个非常难以处理的问题。datepicker 提供了一些选项来帮助解决这些挑战。

时区、日期和格式案例研究

为了在 JavaScript 中处理日期和时间，了解 Date 对象的基础知识是有用的。JavaScript 中的 date 对象本质上是一个 Unix 时间戳（自 1970年1月1日 00:00:00Z 起的毫秒数）。然而，它总是本地化到客户端的时间。这种本地化以与 UTC 的偏移量表示。您浏览器的当前时间是：

客户端（浏览器）时间

当偏移量应用于“时钟时间”时，您将得到 UTC 的当前时间：

UTC

当在日期选择器中使用 value-format 令牌时，这些令牌将使用客户端的时区操作。例如，如果您的格式请求 HH 令牌，它将返回：

HH 格式令牌

将其与上面的日期进行比较，您会看到它与本地时间的 小时 部分相同。为什么这很重要？请继续阅读。

案例研究

让我们考虑一个位于阿姆斯特丹（UTC +100/+200）的餐厅预订应用。它是游客的热门目的地，他们通常会在出行前几周进行预订（当时他们还在自己的国家）。

日期选择器默认情况下会要求游客选择他们希望预订的日期和时间——但（默认情况下）选择的将是他们的本地时间，而不是阿姆斯特丹的时间。即使value-format输出的是UTC，时间也不会是阿姆斯特丹的预定时间（除非他们恰好在同一时区）。

一般来说，有两种解决这个问题的方案：

选项 1：不确定时间

使用一个“不确定”的时间（有时被称为“墙上时间”）。不确定时间是没有与底层Unix时间戳明确关联的时间。例如，3月13日下午2点不是UTC，也没有明确的偏移量。3月13日下午2点描述了一个特定时间在不确定的位置/时区。只要你不在值中使用偏移量（Z），你可以使用格式标记（YYYY-MM-DD HH:mm）来实现这一点。

这对我们的餐厅应用程序来说是可行的，只要后端能够将适当的时区或偏移量附加到这个不确定时间2023-03-13 14:00 GMT+0100，以得到适当的UTC时间（这个虚构的应用程序在其数据库中所需的）。对于后端开发人员来说，剩下的挑战是知道应用于日期的偏移量，以确保它变成“阿姆斯特丹时间”（由于Europe/Amsterdam的夏令时，这个偏移量会根据一年中的时间而变化）。

选项 2：使用日期选择器的timezone属性

另一种方法是，日期选择器的timezone属性会自动为你进行偏移校正。只需声明日期选择器为“哪里”选择时间——在我们的例子中是timezone="Europe/Amsterdam"。用户的体验不会有任何变化，但他们选择的时间将是目标时区的时间。一个在America/New_York（+0400）的用户在他们的日期选择器中选择3月13日下午2点，将产生一个UTC值2023-03-13T13:00:00Z，这是阿姆斯特丹的下午2点。这允许你使用UTC格式简单地存储和恢复你的日期。

不确定时区

默认情况下，日期选择器在选择时使用客户端的本地时区。输出值由value-format决定（见上文）——默认情况下，这是一个UTC标准化的ISO8601字符串。然而，通过指定自定义格式，你可以实现一个“不确定”的时间（也称为“墙上时间”）。这是一个没有与给定时区明确关联的日期和/或时间。

例如，当你在手机上设置上午8:00的闹钟时——那个时间是“不确定的”——它与时区无关。如果你住在罗马，然后旅行到东京，你的闹钟将在东京的上午8:00响起，就像它在罗马的上午8:00响起一样。这是不可能用UTC来表示的。

你可以通过在value-format中不提供任何时区或偏移信息来使用日期选择器实现不确定时间——解释日期的人有责任添加那些信息。value-format中的标记总是输出本地客户端值——所以通过省略值中的任何时区或偏移（Z）数据，它本质上是“不确定的”：

指定时区

对于某些应用程序来说，选择给定位置的时间是必要的——这可能相当具有挑战性。为了帮助缓解这种困难，日期选择器支持明确指定输入的 timezone。

timezone 属性允许您根据浏览器支持的 IANA 时区 来指定日期选择器的“位置”。当您希望允许用户选择一个给定地理位置的日期和时间，无论客户端的位置如何时，这一点非常重要。一些示例用例包括：

• 餐厅预订
• 租车取车时间
• 酒店入住时间

有很多情况下不应该使用 timezone（默认为客户端时间）：

• 安排 Zoom 会议
• 设置提醒通知
• 创建日历事件

在下面的示例中，用户需要在国际航班后在印度加尔各答取一辆租赁车。用户查看他们的机票——航班抵达加尔各答的时间为 下午 1:45。他们希望在 45 分钟后的 下午 2:30 提车。无论用户从世界上哪个地方预订旅行，这些事实都是真实的。在这种情况下，我们应该将时区设置为 亚洲/加尔各答。加尔各答的偏移量是 +5:30 —— 因此，在 加尔各答 选择 下午 2:30 相当于 上午 09:00 UTC：

禁用日期

在日期选择器中禁用特定日期通常是必要的。在日期选择器中禁用日期有三种方式：

• min-date - 一个属性，用于控制第一个可用日期是什么。
• max-date - 一个属性，用于控制最后一个可用日期是什么。
• disabled-dates - 一个属性，用于控制是否应该禁用任意日期。

任何被禁用的日期都不能在日期选择器的弹出窗口中被选择，然而，一个不可用的日期仍然可以被设置为初始值或通过输入到输入框中（当它不处于 picker-only 模式时）。为了处理这些边缘情况，日期选择器内置了一个验证规则（不能被禁用），以确保只有有效的日期可以被提交。验证规则的关键是 invalidDate。

最小日期

通常需要禁用早于特定日期的日期。例如，预订酒店房间只应该选择未来的日期。要做到这一点，请使用 min-date 属性，并搭配 ISO8601 兼容字符串或原生 Date 对象：

最大日期

要禁用在给定日期之后的所有日期，请使用 max-date 属性。例如，生日选择器应该只允许选择过去的日期。要做到这一点，请使用 max-date 属性，并搭配 ISO8601 兼容字符串或原生 Date 对象：

禁用的天数

我们的应用程序通常需要比 min-date 和 max-date 允许的更细粒度的控制来禁用日期。日期选择器通过利用 disabled-days 属性提供了细粒度的控制。

disabled-days 属性期望一个函数，该函数接收 2 个参数：核心节点和一个 Date 对象。该函数的责任是返回一个布尔值，指示日期是否被禁用（true 表示禁用）。

disabled-days 属性优先于 min-date 和 max-date —— 你可以选择通过访问 node.props.minDate 或 node.props.maxDate 来重新实现基础功能。

示例：禁用周末

示例：从 API 获取

扫描可用性

当通过键盘导航日历弹出窗口时，日期选择器不会允许你选择一个被禁用的日期。然而，这可能会令人恼火，因为如果一些可用日期被不可用的日期“夹在中间”，会造成无法访问的区域。

为了提供更好的用户体验，日期选择器会自动向前或向后扫描（取决于所需的方向），以寻找下一个可选的日期。控制扫描可用日期的最大天数由 maxScan 属性控制（默认为 7 天）：

示例：max-scan

可清除

当输入框有值时，可以通过点击出现的“清除”按钮来清除日期选择器输入框的内容 — 这个清除按钮只有在添加了 clearable 属性时才会出现：

属性 & 参数

部分

您可以使用该部分的“键”来定位输入的特定部分，允许您修改该部分的类、HTML（通过:sections-schema）或内容（通过插槽）。在这里阅读更多关于部分的信息。

覆盖层

当添加了overlay属性时，此部分位于inner部分内部。

年份面板

当日期选择器弹出窗口打开时，面板出现在inner部分下方的输入元素下面。

月份面板

当日期选择器弹出时，该面板出现在 inner 部分的输入元素下方。

日面板

当日期选择器弹出时，该面板出现在 inner 部分的输入元素下方。

时间面板

当日期选择器弹出窗口打开时，面板会出现在 inner 部分的输入元素下方。

部分关键词

可访问性

所有 FormKit 输入都是考虑到以下可访问性因素而设计的。通过在此处提交可访问性问题，帮助我们不断改进所有人的可访问性：

键盘交互