TimePicker 时间选择器

用于选择时间。

基础选择

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

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 调整分钟选项的间隔。已有值的分钟不在间隔内时，仍会保留为可选项。

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 小时格式。

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

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) => boolean`	—	按业务规则禁用时间，输入和面板选择使用同一规则。
`disabled`	`boolean`	`false`	禁用交互。
`name`	`string`	—	原生 FormData 中的字段名。
`form`	`string`	—	关联的原生表单 ID。
`required`	`boolean`	`false`	要求整体值非空，复合控件只校验一次。
`ref`	`Ref<HTMLInputElement>`	—	输入框引用

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

类型

可导入 TimePickerProps 定义组件属性，或单独使用尺寸、校验状态类型：

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。

#TimePicker 时间选择器

#基础选择

#受控与分钟间隔

#12 小时制与秒

#禁用时间

#TimePicker API

#类型

#使用说明

#TimeParts