时间输入框

TimeInput 组件由标签和一组表示时间单位（例如，小时、分钟和秒）的片段组成。每个片段都可以单独聚焦和编辑，用户可以通过键入或使用箭头键来增加和减少值。这种方法允许正确格式化和解析值，而无需考虑区域设置或时间格式，并提供了一种使用键盘轻松且无错误地编辑时间的方法。

安装

上述命令仅用于单独安装。如果已全局安装，则可以跳过此步骤 @heroui/react。

导入

用法

默认情况下，TimeInput 显示占位符。可以使用 defaultValue 属性为 TimeField 提供初始的非受控值。或者，可以使用 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 属性为 TimeInput 提供初始的、非受控的值。可以使用 value 属性提供受控的值。

时区

当 TimeInput 的值是 ZonedDateTime 对象时，它会感知时区。在这种情况下，会显示时区缩写，并且在操作值时会考虑时区问题，例如夏令时。

在大多数情况下，您的数据将来自服务器并发送到服务器，格式为 ISO 8601 格式的字符串。@internationalized/date 包含将多种格式的字符串解析为 ZonedDateTime 对象的功能。您使用的格式将取决于您需要存储的信息。

• parseZonedDateTime – 此函数解析带有显式时区和可选 UTC 偏移量的日期（例如，2021-11-07T00:45[America/Los_Angeles] 或 2021-11-07T00:45-07:00[America/Los_Angeles]）。此格式保留最大量的信息。如果用户选择的确切本地时间和时区很重要，请使用此格式。存储所选的时区和偏移量而不是转换为 UTC 可确保本地时间正确，而与夏令时规则的更改无关（例如，如果某个地区废除了夏令时）。适用此格式的示例包括日历事件、提醒以及发生在特定位置的其他时间。
• 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 还控制用户首次与每个分段交互时的默认值，例如使用向上和向下箭头键。默认情况下，placeholderValue 是午夜，但如果需要，您可以将其设置为更合适的值。

隐藏时区

当为 TimeInput 提供 ZonedDateTime 对象作为值时，默认情况下会显示时区缩写。但是，如果时区缩写在其他地方显示或根据用例是隐式的，则可以使用 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 属性。

可访问性

• 支持特定于语言环境的格式、数字系统、小时周期和从右到左的布局。
• 时间可以可选地包含时区。所有修改都遵循时区规则，例如夏令时。
• 每个时间单位都显示为单独可聚焦和可编辑的段，这使用户可以轻松地使用键盘以任何格式和语言环境编辑时间。
• 时间段可以使用易于使用的数字键盘进行编辑，并且所有交互都可以使用基于触摸的屏幕阅读器进行访问。

API

TimeInput Props

TimeInput Events