时间输入

TimeInput 组件由标签和一组表示时间各个单位（例如小时、分钟和秒）的段落组成。每个段落均可单独聚焦并编辑，用户可通过键盘输入或使用方向键递增/递减数值。此方式能确保无论本地化格式如何，都能正确格式化和解析数值，并提供一种简洁且无错误的键盘编辑方式。

安装

The above command is for individual installation only. You may skip this step if @heroui/react is already installed globally.

导入

使用

TimeInput 默认显示占位符。可以通过 defaultValue 属性提供一个初始无控值；或者通过 value 属性提供受控值。

时间值使用 @internationalized/date 包中的对象来提供。该库能正确处理不同日历、时区以及其他本地化需求的国际化日期时间操作。

TimeInput 仅支持时间选择，但同时也接受包含日期组件的值。默认情况下，TimeInput 在 onChange 事件中返回 Time 对象；若将 CalendarDateTime 或 ZonedDateTime 对象传递给 value 或 defaultValue，返回值将为该类型，仅修改时间并保留日期组件。

必填

TimeInput 支持 isRequired 属性，以确保用户在提交表单前输入值，同时支持最小/最大值及自定义客户端/服务端校验。

禁用

isDisabled 布尔属性使 TimeInput 被禁用。输入框无法获得焦点或被选中。

只读

isReadOnly 布尔属性使 TimeInput 的值不可修改。与 isDisabled 不同，TimeInput 仍可获得焦点。

无标签

TimeInput 支持 label 属性，用于显示或隐藏标签。

带描述

字段描述，提供如选择要求等提示。

带错误信息

可以组合使用 isInvalid 与 errorMessage 来显示无效输入。

也可以将错误信息作为函数传递。这样可根据 ValidationResult 动态处理错误信息。

标签位置

标签相对于其关联元素的整体位置。

首部内容

若想在时间输入前显示一些内容，可设置 startContent 属性。

尾部内容

若想在时间输入后显示一些内容，可设置 endContent 属性。

受控

如前所述，可通过 defaultValue 提供一个初始无控值，或者通过 value 提供受控值。

时区

当传递 ZonedDateTime 对象作为值时，TimeInput 具备时区感知功能。在此情况下，会显示时区缩写，并在处理值时考虑夏令时等时区规则。

在大多数场景下，您的数据会以 ISO 8601 格式字符串发送至服务器。@internationalized/date 提供了解析多种格式字符串为 ZonedDateTime 对象的函数。您使用哪种格式取决于所需存储信息。

• parseZonedDateTime – 解析带显式时区及可选 UTC 偏移的日期（如 2021-11-07T00:45[America/Los_Angeles] 或 2021-11-07T00:45-07:00[America/Los_Angeles]）。此格式保留了最多信息。若需要保留用户选择的当地时间和时区，使用此格式。存储所选时区和偏移而非转换为 UTC，可确保即使夏令时规则变更（如某个地区废除 DST）也能保持当地时间准确。此类场景包括日历事件、提醒以及其它发生在特定地点的时间。
• parseAbsolute – 解析在所有地点均为同一瞬间的绝对日期和时间，可用 UTC 表示（如 2021-11-07T07:45:00Z），亦可带特定偏移存储（如 2021-11-07T07:45:00-07:00）。必须传入时区标识（如 America/Los_Angeles），结果将转换为该时区。绝对时间是表示过去事件或未来需精确时间的最佳方式，无论时区如何。
• parseAbsoluteToLocal – 将绝对日期时间解析为当前用户的本地时区。它是 parseAbsolute 的快捷方式，接受相同格式。

粒度

granularity 属性允许你控制 TimeInput 中显示的最小单位。默认情况下，时间以 “分钟” 的粒度显示。你可以通过将 granularity 设置为 “second” 来显示更细粒度的秒值。

最小时间值

minValue 属性允许你在某一时间之前进行时间值验证。

最大时间值

maxValue 属性允许你在某一时间之后进行时间值验证。

占位符值

当未设置值时显示占位符。占位符格式受 granularity 与 placeholderValue 属性影响。placeholderValue 同时控制用户首次交互时每个段落的默认值，例如使用上下箭头键。默认占位符为午夜，但可根据需要设置更合适的值。

隐藏时区

当 ZonedDateTime 对象作为值传递给 TimeInput 时，默认显示时区缩写。若此信息已在其他位置展示或从用例推断可见，则可通过 hideTimeZone 选项隐藏。

小时周期

默认情况下，TimeInput 根据用户本地化信息显示 12 或 24 小时格式。然而，如需针对特定用例覆盖，可使用 hourCycle 属性。此示例强制 TimeInput 使用 24 小时制，无论本地化如何。

插槽

• base: 输入包装器，处理对齐、放置与整体外观。
• label: 时间输入的标签，显示在上方、内部或左侧。
• inputWrapper: 包含 label（当其位于内部时）与 innerWrapper。
• input: 时间输入元素。
• innerWrapper: 包含段落、startContent 与 endContent。
• segment: 输入段落。
• helperWrapper: 协助文本包装器，包含辅助文本与错误信息。
• description: 时间输入描述。
• errorMessage: 时间输入错误信息。

数据属性

TimeInput 在 base 元素上具有以下属性：

• data-has-helper: 当时间输入有描述或错误信息时。基于 description 或 errorMessage 属性。
• data-required: 当时间输入为必填时。基于 isRequired 属性。
• data-disabled: 当时间输入被禁用时。基于 isDisabled 属性。
• data-readonly: 当时间输入为只读时。基于 isReadOnly 属性。
• data-invalid: 当时间输入无效时。基于 isInvalid 属性。
• data-has-start-content: 当时间输入有首部内容时。基于 startContent 属性。
• data-has-end-content: 当时间输入有尾部内容时。基于 endContent 属性。

可访问性

• 支持本地化格式、数字系统、小时周期以及 RTL 布局。
• 时间可选包含时区。所有修改均遵循时区规则，如夏令时。
• 每个时间单位以可单独聚焦并编辑的段落形式呈现，让用户能够轻松使用键盘在任意格式与本地化下编辑时间。
• 时间段可使用数字键盘编辑，所有交互均兼容触摸屏阅读器。

API

TimeInput Props

TimeInput Events