Datepicker

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

基本示例

datepicker 输入允许用户从可自定义的日历中选择日期，并直接在输入中输入日期，支持完整的国际化。

模式

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

双重输入

• 文本输入 - 默认情况下，用户可以点击或选项卡进入显示日期（月、日、年等）的任何“部分”中的文本输入，并输入所需的值。将显示匹配的值并自动完成。除了输入，用户还可以按上/下箭头键在每个段中循环浏览可用选项。
• 选择器输入 - 通过点击输入框右侧的“日历”图标，用户还可以显示日历弹出窗口以直观地选择日期：

仅选择器

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

日期格式

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

样式格式

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

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

日期样式

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

时间样式

令牌格式

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

FormKit 通过 Intl.DateTimeFormat 接口自动根据当前 locale 国际化令牌。例如，对于 2000-01-01，MMMM 令牌在 en 区域设置下会生成 January，而在 zh 区域设置下会生成 一月。

转义标记

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

面板顺序

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

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

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

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

选择时间

time 面板可用于允许用户选择一天中的特定时间。如果您选择包含时间的 format（如 YYYY-MM-DD HH:mm），您可能需要将 time 面板添加到序列中：

值

与所有输入一样，日期选择器的 value 既是由日期选择器生成的内容，也是读回到日期选择器中进行填充的内容。默认情况下，值的格式是 UTC 标准化的 ISO8601 字符串（示例：2014-11-27T03:59:00.000Z）。但是，可以通过使用 value-format prop 将此格式更改为上面列出的任何支持的日期样式或标记格式之一（＃date-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 提供了一些选项来帮助解决这些挑战。

不确定时区

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

例如，当您为手机设置一个 8:00 AM 的闹钟时，那个时间是“不确定”的，它与时区无关。如果您住在罗马，然后去东京，您的闹钟会在东京的 8:00 AM 响，就像它在罗马的 8:00 AM 一样。这是不可能表示为 UTC 的。

您可以通过在 value-format 中不提供时区或偏移信息来实现日期选择器的不确定时间 —— 解释日期的人需要添加这些信息。value-format 中的令牌总是输出本地客户端值 —— 通过将任何时区或偏移（Z）数据从值中排除，它本质上是“不确定”的：

指定时区

对于某些应用程序，需要选择给定位置的时间，这可能相当具有挑战性。为了帮助解决这个问题，日期选择器支持显式指定输入的timezone。

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

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

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

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

在下面的示例中，用户需要在国际航班后在印度加尔各答取一辆租赁汽车。用户查看他们的机票 - 航班到达加尔各答的时间为1:45 PM。他们希望在45分钟后的2:30 PM取车。无论用户从世界上的哪个地方预订行程，这些事实都是真实的。在这种情况下，我们应该将时区设置为Asia/Kolkata。加尔各答的偏移量为+5:30 - 因此，在Kolkata选择2:30 PM相当于09:00 AM 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

属性 & 属性

部分

您可以使用部分的 "key" 定位输入的特定部分，从而修改该部分的类、HTML（通过 :sections-schema）或内容（通过插槽）。在此处阅读有关部分的更多信息。

覆盖层

当添加 overlay prop 时，此部分位于 inner 部分内。

年份面板

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

月份面板

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

天数面板

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

时间面板

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

部分键