时间输入框

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

安装

上述命令仅用于单独安装。如果 @nextui-org/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 属性提供一个受控制的值。

时区

当提供 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，可以确保本地时间在夏令时规则更改时（例如，如果某个地区废除了夏令时）仍然正确。适用此情况的示例包括日历事件、提醒以及在特定地点发生的其他时间。
• parseAbsolute – 此函数解析在地球上所有位置的同一时刻发生的绝对日期和时间。它可以用 UTC 表示（例如，2021-11-07T07:45:00Z），或者存储一个特定的偏移量（例如，2021-11-07T07:45:00-07:00）。必须传递一个时区标识符，例如 America/Los_Angeles，结果将转换为该时区。绝对时间是表示过去发生的事件或需要精确时间的未来事件的最佳方式，无论时区如何。
• parseAbsoluteToLocal – 此函数将绝对日期和时间解析为当前用户的本地时区。它是 parseAbsolute 的快捷方式，并接受相同的格式。

粒度

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

最小时间值

minValue 属性允许您在某个时间之前验证时间值。

最大时间值

maxValue 属性允许您在某个时间之前验证时间值。

占位符值

当未设置值时，会显示一个占位符。占位符的格式受 granularity 和 placeholderValue 属性的影响。当用户首次与它们交互时（例如，使用向上和向下箭头键），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 属性。

可访问性

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

API

TimeInput 属性

TimeInput 事件