Datepicker

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

基本示例

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

模式

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

双重输入

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

仅选择器

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

日期格式

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

样式格式

如果您的受众是国际性的，您应该考虑坚持使用"样式日期"，因为它们是每个地区最自然的日期格式。日期选择器的默认格式是 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 属性来修改哪些面板应该显示给用户，以及这些面板应该按什么顺序显示。默认的 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 提供了一些选项来帮助解决这些挑战。

不确定的时区

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

例如，当你在手机上设置一个早上8:00的闹钟时 - 那个时间是"不确定"的 - 它与时区无关。如果你住在罗马，然后去东京，你的闹钟会在东京的早上8:00响，就像在罗马的早上8:00一样。这是无法用UTC表示的。

你可以通过在你的value-format中不提供任何时区或偏移信息，来使用日期选择器实现不确定的时间 - 添加这些信息取决于日期的解释者。value-format中的令牌总是输出本地客户端的值 - 所以，通过在值中省略任何时区或偏移（Z）数据，它本质上就是"不确定"的：

指定时区

对于一些应用程序，需要选择给定位置的时间 - 这可能相当具有挑战性。为了帮助缓解这种痛苦，日期选择器支持明确指定输入的 timezone。

timezone 属性允许您根据浏览器支持的 IANA 时区 指定日期选择器的 "位置"。当您希望允许用户在给定地理位置选择日期和时间时，这很重要，无论客户端的位置在哪里。一些示例用例包括：

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

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

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

在下面的例子中，用户需要在国际航班后在印度加尔各答取一辆租赁车。用户查看他们的票 - 飞机在加尔各答的到达时间为 1:45 PM。他们希望在 2:30 PM 之后的 45 分钟内取车。无论用户从世界上的哪个地方预订旅行，这些事实都是真实的。在这种情况下，我们应该将时区设置为 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

属性 & 属性

部分

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

覆盖层

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

年份面板

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

月份面板

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

日面板

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

时间面板

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

部分键