> Leaf UI 0.6.0 · Package: @ifhover/leaf-ui · Source: b30c3d3a8fa9c5e15d0d0522cebfbd33f60c6b06
> Browser documentation: https://ifhover.github.io/leaf-ui/v/0.6.0/components/time-picker.html

> For AI agents: the complete documentation index is available at https://ifhover.github.io/leaf-ui/v/0.6.0/llms.txt, the full documentation bundle is available at https://ifhover.github.io/leaf-ui/v/0.6.0/llms-full.txt.

# TimePicker 时间选择器

用于选择时间。

## 基础选择

输入时间或在面板中选择小时、分钟和秒，点击确定后生效。关闭面板会放弃未确认的调整。


选择时间

默认时间

禁用时间

basic.tsx

复制代码

```tsx lineNumbers file="../../src/examples/time-picker/basic.tsx"
import { Form, FormField, TimePicker } from '@ifhover/leaf-ui';

export function TimePickerBasic() {
  return (
    <Form layout="vertical">
      <FormField label="选择时间">
        <TimePicker aria-label="选择时间" />
      </FormField>
      <FormField label="默认时间">
        <TimePicker aria-label="默认时间" defaultValue="09:30" />
      </FormField>
      <FormField label="禁用时间">
        <TimePicker aria-label="禁用时间" defaultValue="18:00" disabled />
      </FormField>
    </Form>
  );
}
```

展开代码

## 受控与分钟间隔

通过 `value` / `onChange` 管理值，`minuteStep` 调整分钟选项的间隔。已有值的分钟不在间隔内时，仍会保留为可选项。


会议时间

以 15 分钟为间隔，当前值：14:30

保留不符合间隔的已有值

controlled.tsx

复制代码

```tsx lineNumbers file="../../src/examples/time-picker/controlled.tsx"
import { Form, FormField, Text, TimePicker } from '@ifhover/leaf-ui';

import { useState } from 'react';

export function TimePickerControlled() {
  const [time, setTime] = useState<string | null>('14:30');
  return (
    <Form layout="vertical">
      <FormField label="会议时间">
        <TimePicker aria-label="会议时间" value={time} onChange={setTime} minuteStep={15} />
      </FormField>
      <Text tone="muted">以 15 分钟为间隔，当前值：{time || '未选择'}</Text>
      <FormField label="保留不符合间隔的已有值">
        <TimePicker aria-label="保留时间" defaultValue="08:07" minuteStep={15} allowClear={false} />
      </FormField>
    </Form>
  );
}
```

展开代码

## 12 小时制与秒

设置 `use12Hours` 展示上午、下午选项；`showSeconds` 开启秒。12 小时制只改变显示，值仍使用 24 小时格式。


12小时制

精确到秒

twelve-hours.tsx

复制代码

```tsx lineNumbers file="../../src/examples/time-picker/twelve-hours.tsx"
import { Form, FormField, TimePicker } from '@ifhover/leaf-ui';

export function TimePickerTwelveHours() {
  return (
    <Form layout="vertical">
      <FormField label="12小时制">
        <TimePicker aria-label="12小时制" use12Hours defaultValue="14:30" />
      </FormField>
      <FormField label="精确到秒">
        <TimePicker
          aria-label="精确到秒"
          use12Hours
          showSeconds
          secondStep={10}
          defaultValue="00:05:30"
        />
      </FormField>
    </Form>
  );
}
```

展开代码

## 禁用时间


营业时间；禁用项无法选择或通过输入提交

capabilities.tsx

复制代码

```tsx lineNumbers file="../../src/examples/time-picker/capabilities.tsx"
import { Flex, Space, TimePicker } from '@ifhover/leaf-ui';

export function Capabilities() {
  return (
    <Space direction="vertical" align="stretch">
      <Flex direction="column" gap="sm" align="center">
        {'营业时间；禁用项无法选择或通过输入提交'}
        <TimePicker
          use12Hours
          defaultValue="09:30"
          disabledTime={(time) => time.hour < 9 || time.hour >= 18}
          minuteStep={15}
        />
      </Flex>
    </Space>
  );
}
```

展开代码

## TimePicker API

| 属性                  | 类型                                                                                                                                                                   | 默认值     | 说明                         |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | -------------------------- |
| `popupPlacement`    | `'top' \| 'top-start' \| 'top-end' \| 'bottom' \| 'bottom-start' \| 'bottom-end' \| 'left' \| 'left-start' \| 'left-end' \| 'right' \| 'right-start' \| 'right-end'` | —       | 浮层相对触发控件的位置。               |
| `popupClassName`    | `string`                                                                                                                                                             | —       | 浮层的自定义类名。                  |
| `popupStyle`        | `CSSProperties`                                                                                                                                                      | —       | 浮层的自定义样式。                  |
| `popupRender`       | `(content: React.ReactNode) => React.ReactNode`                                                                                                                      | —       | 包装或补充面板内容，保留传入的内容以维持交互。    |
| `getPopupContainer` | `() => Element \| DocumentFragment`                                                                                                                                  | —       | 返回浮层的挂载容器，也可返回 ShadowRoot。 |
| `size`              | `'sm' \| 'md' \| 'lg'`                                                                                                                                               | `'md'`  | 选择器尺寸                      |
| `status`            | `'error' \| 'warning'`                                                                                                                                               | —       | 校验状态                       |
| `allowClear`        | `boolean`                                                                                                                                                            | `true`  | 展示清除按钮                     |
| `inputReadOnly`     | `boolean`                                                                                                                                                            | —       | 只禁止手动输入，仍可在面板中选择。          |
| `open`              | `boolean`                                                                                                                                                            | —       | 控制面板是否展开。                  |
| `defaultOpen`       | `boolean`                                                                                                                                                            | —       | 面板初始展开状态。                  |
| `value`             | `string \| null`                                                                                                                                                     | `null`  | `HH:mm` 格式的受控值 / 初始值       |
| `defaultValue`      | `string \| null`                                                                                                                                                     | `null`  | `HH:mm` 格式的受控值 / 初始值       |
| `minuteStep`        | `number`                                                                                                                                                             | `5`     | 分钟间隔，使用 1–60 的整数           |
| `secondStep`        | `number`                                                                                                                                                             | `1`     | 秒间隔，使用 1–60 的整数            |
| `showSeconds`       | `boolean`                                                                                                                                                            | `false` | 显示秒选项，值使用 HH:mm:ss         |
| `use12Hours`        | `boolean`                                                                                                                                                            | `false` | 展示 12 小时制及上午、下午选项          |
| `onChange`          | `(value: string \| null) => void`                                                                                                                                    | —       | 确认选择时返回 HH:mm，清除时返回 null   |
| `onOpenChange`      | `(open: boolean) => void`                                                                                                                                            | —       | 面板展开或收起                    |
| `disabledTime`      | `(parts: `[`TimeParts`](#timeparts)`) => boolean`                                                                                                                    | —       | 按业务规则禁用时间，输入和面板选择使用同一规则。   |
| `disabled`          | `boolean`                                                                                                                                                            | `false` | 禁用交互。                      |
| `name`              | `string`                                                                                                                                                             | —       | 原生 FormData 中的字段名。         |
| `form`              | `string`                                                                                                                                                             | —       | 关联的原生表单 ID。                |
| `required`          | `boolean`                                                                                                                                                            | `false` | 要求整体值非空，复合控件只校验一次。         |
| `ref`               | `Ref<HTMLInputElement>`                                                                                                                                              | —       | 输入框引用                      |

其余原生 input 属性和 `aria-*` 透传至输入框；`className` / `style` 作用于外层容器。

## 类型

可导入 [`TimePickerProps`](#timepicker-api) 定义组件属性，或单独使用尺寸、校验状态类型：

```ts
import type { TimePickerProps, ControlSize, ControlStatus } from '@ifhover/leaf-ui';
```

## 使用说明

传入 `00:00` 至 `23:59` 的有效时间；开启秒时使用 `HH:mm:ss`。时间值不包含日期或时区。未选择时面板从 09:00 开始，打开面板本身不会改变值。所有模式都通过底部确定按钮提交。

设置 `name` 后，FormData 提交 HH:mm 或 HH:mm:ss 字符串，清除后为空字符串。非受控组件支持表单 reset；受控组件需重置自己的状态。

点击输入框打开面板，↓ 移入选项。↑ / ↓ 在列内移动，Home / End 移至首尾；Tab 在小时、分钟及确认之间移动，Enter 选择或确认。Escape 放弃调整并收起；Tab 离开面板后聚焦表单中的后续控件。面板继承局部主题。

可直接输入 `HH:mm` 或 `HH:mm:ss`，12 小时制输入支持 AM/PM 或上午/下午。按 Enter 确认输入，也可在面板中调整后点击确定。“当前时间”将草稿设为当前时间，仍需确定。无效时间不会提交；移走焦点或 Escape 放弃未确认内容。

## TimeParts

| 属性       | 类型       | 默认值 | 说明            |
| -------- | -------- | --- | ------------- |
| `hour`   | `number` | —   | 必需。设置 hour。   |
| `minute` | `number` | —   | 必需。设置 minute。 |
| `second` | `number` | —   | 必需。设置 second。 |