# 时间输入 · TimeInput

- 页面: https://jiguang132.com/zh/resources/astryx/docs/time-input
- 资源: Astryx (https://jiguang132.com/zh/resources/astryx.md)
- 全部指南: https://jiguang132.com/zh/resources/astryx/docs.md

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

## 安装与前置条件

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

需要 React 19+，按顺序导入基础 CSS 和主题，并设置 Theme Provider。参见[开始使用](/resources/astryx/docs/getting-started)。

## 示例与使用方式

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

## API 与上游详细参考

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

## Time Input

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

| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| label * | string |  | 输入框的标签文本（无障碍性所必需）。 |
| isLabelHidden | boolean | false | 视觉上隐藏标签，同时保持屏幕阅读器的无障碍性。 |
| description | string |  | 显示在标签和输入框之间的描述文本。 |
| isOptional | boolean | false | 在标签旁显示"（可选）"指示器。与 isRequired 互斥。 |
| isRequired | boolean | false | 将字段标记为必填并设置 aria-required。与 isOptional 互斥。 |
| isDisabled | boolean | false | 禁用输入框并抑制交互。 |
| disabledMessage | string |  | 说明输入框为何被禁用。与 isDisabled 一起使用时，在悬停/键盘聚焦时显示提示，并通过 aria-disabled 保持输入框可聚焦（仍阻止输入和调整）。请使用此属性，而不是用 Tooltip 包裹已禁用的 TimeInput。 |
| value | ISOTimeString |  | ISO 格式的受控时间值（HH:MM 或 HH:MM:SS）。 |
| onChange | (value: ISOTimeString \| undefined) => void |  | 时间变化时触发的回调。输入被清除时接收 undefined。 |
| changeAction | (value: ISOTimeString \| undefined) => void \| Promise<void> |  | 在 onChange 之后触发的异步操作。包装在 React transition 中以提供乐观 UI；挂起时触发加载旋转器。 |
| isLoading | boolean | false | 使输入框进入加载状态，显示旋转器。 |
| min | ISOTimeString |  | ISO 格式的最小可选时间。超出范围的值将被拒绝。 |
| max | ISOTimeString |  | ISO 格式的最大可选时间。超出范围的值将被拒绝。 |
| hasSeconds | boolean | false | 在时间显示和解析中包含秒。 |
| hasClear | boolean | false | 当有值且输入框未被禁用时显示清除按钮。 |
| hourFormat | '12h' \| '24h' | '12h' | 控制显示格式。'12h' 显示 AM/PM（例如 '2:30 PM'）；'24h' 使用 24 小时制（例如 '14:30'）。 |
| increment | number | 1 | 用户按上或下方向键时增加或减少的分钟数。 |
| presentation | 'text-input' \| 'popover' \| 'bottom-sheet' \| 'native' \| 'adaptive-bottom-sheet' \| 'adaptive-native' | 'adaptive-native' | 选择时间所用的界面。'adaptive-native'（默认）在精细指针上使用 Astryx 文本字段、在粗指针上使用浏览器/操作系统 input type=time——但 hasSeconds 或 increment 不为 1 时保留文本字段；'native' 始终使用浏览器/操作系统控件且不回退；'adaptive-bottom-sheet' 在精细指针上用文本字段、在粗指针上用 Astryx 底部滚轮选择器；'bottom-sheet' 在任何指针上强制使用滚轮；'text-input'（与无独立界面的 'popover' 相同）只保留文本字段。原生模式会传递 min/max 并在提交时强制校验。hourFormat 控制关闭状态的显示；打开的系统选择器遵循设备区域设置。 |
| nativePicker | 'touch' \| 'always' \| 'never' | 'touch' | 已弃用：请使用 presentation（'touch'='adaptive-native'、'always'='native'、'never'='text-input'）。仍按已发布行为工作；同时设置时以 presentation 为准。 |
| placeholder | string | 'Select a time' | 未选择时间时显示的占位符文本。当输入框聚焦且为空时，格式提示会覆盖此文本。 |
| size | 'sm' \| 'md' \| 'lg' | 'md' | 控制输入框元素的高度。 |
| status | {type: 'warning' \| 'error' \| 'success', message?: string} |  | 为边框着色并显示图标的状态指示器。当提供消息时，消息渲染在输入框下方。 |
| statusVariant | 'attached' \| 'detached' \| 'tooltip' | 'attached' | 状态消息相对于输入框的放置方式。attached 直接叠加在输入框下方（带边框处理）；detached 作为独立元素浮于下方并留有间距；tooltip 隐藏消息框，并在状态图标上以提示气泡形式显示。 |
| labelTooltip | string |  | 在标签行末尾以信息图标形式渲染的工具提示文本。 |
| width | SizeValue |  | Width of the field (number = pixels, string used as-is, e.g. "100%"). Sizes the whole field (label, control, and status) so they stay aligned. |
| containerXstyle | StyleXStyles |  | 作用于包含标签、控件和状态的 Field 容器的 StyleX 样式；containerClassName 与 containerStyle 以类名和内联样式作用于同一容器。没有 Field 容器时（InputGroup 内或 horizontal-labels FormLayout 中）不生效，并在开发环境发出警告。 |
| controlXstyle | StyleXStyles |  | 作用于可见控件框（带边框、包含文本、图标和末端控件的元素，而非原生 input）的 StyleX 样式；controlClassName 与 controlStyle 以类名和内联样式作用于同一元素。本组件不接受根级 xstyle、className 和 style。 |

### 使用建议

- 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

```json
{
  "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.

---

JGuang 全部资源索引: https://jiguang132.com/llms.txt