时间输入 · TimeInput

输入或选择时间，遵循原生格式和校验 API。

安装与前置条件

npm install @astryxdesign/core@0.7.1 @astryxdesign/theme-neutral@0.7.1 @stylexjs/stylex@0.19.0

需要 React 19+，按顺序导入基础 CSS 和主题，并设置 Theme Provider。参见开始使用。

示例与使用方式

• 时间输入 · 综合展示 1：首先体验这个示例，再查看代码理解组件的组合方式。
• 时间输入 · 交互示例 2：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
• 时间输入 · 交互示例 3：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
• 时间输入 · 交互示例 4：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
• 时间输入 · 多种状态 5：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。

API 与上游详细参考

优先使用 0.7.1 官方中文说明；上游尚未提供中文的条目保留英文。属性名、类型及默认值保持原生 API，不把示例状态名称当成组件属性。

Time Input

TimeInput 默认在粗指针设备上使用浏览器/操作系统的时间选择器，在精细指针设备上使用 Astryx 文本字段。它将时间转换为标准格式，并在文本字段界面支持方向键调整。适用于表单、排期流程和其他时间选择场景。

使用建议

• Base props such as ref, id, data-, aria-, and DOM event handlers go to the time input, the element that is focused and announced. A DOM handler runs after TimeInput's own handler for the same event and still receives events it handled (including ones it called preventDefault on), so it cannot cancel built-in behavior.
• Choose the hour format (12h or 24h) that matches your audience's locale: 12-hour with AM/PM for US-centric UIs, 24-hour for international or technical contexts.
• Set min and max constraints when the context has a valid range, like business hours or event windows, so users cannot submit an out-of-bounds time.
• Provide a description or placeholder that hints at the expected format or purpose, like "Business hours: 9 AM – 5 PM".
• Use the status prop to surface validation errors inline: show a message like "Time must be during business hours" so users know exactly what to fix.
• Enable hasClear when the field is optional, so users can remove a previously selected time.
• 避免：Don't use TimeInput for combined date-and-time selection; pair it with a separate DateInput instead.
• 避免：Don't hide the label; even when space is tight, keep the label visible or provide a description so the purpose is clear.
• 避免：Wrap a disabled TimeInput in Tooltip to explain why it is disabled; disabled triggers swallow the hover events the wrapper needs. Use the disabledMessage prop instead.

主题 API

{
  "targets": [
    {
      "className": "astryx-time-input",
      "visualProps": [
        "size",
        "status"
      ],
      "states": [
        "disabled"
      ]
    }
  ]
}

组件结构

• Clock icon: 用于识别时间字段的前置时钟图标；在原生模式下也可打开浏览器/操作系统选择器。
• Time control: 原生模式下使用真正的 input type=time；精细指针、presentation="text-input"、秒或自定义步进场景使用 Astryx 可编辑文本字段。
• Clear button: A trailing button to reset the value, shown when hasClear is true and a value is set.
• Status icon: A trailing icon indicating error, warning, or success state.
• Spinner: Replaces trailing content during loading to show an async action is in progress.