TimePicker 时间选择器

用于选择时间。

基础选择

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

交互预览基础选择

basic.tsx

import { TimePicker } from '@sudden3/leaf-ui';

export function TimePickerBasic() {
  return (
    <div className="leaf-demo-stack">
      <TimePicker aria-label="选择时间" />
      <TimePicker aria-label="默认时间" defaultValue="09:30" />
      <TimePicker aria-label="禁用时间" defaultValue="18:00" disabled />
    </div>
  );
}

受控与分钟间隔

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

交互预览受控与分钟间隔

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

controlled.tsx

import { TimePicker } from '@sudden3/leaf-ui';
import { useState } from 'react';

export function TimePickerControlled() {
  const [time, setTime] = useState<string | null>('14:30');
  return (
    <div className="leaf-demo-stack">
      <TimePicker aria-label="会议时间" value={time} onChange={setTime} minuteStep={15} />
      <span className="leaf-demo-note">以 15 分钟为间隔，当前值：{time || '未选择'}</span>
      <TimePicker aria-label="保留时间" defaultValue="08:07" minuteStep={15} allowClear={false} />
    </div>
  );
}

12 小时制与秒

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

交互预览12 小时制与秒

twelve-hours.tsx

import { TimePicker } from '@sudden3/leaf-ui';
export function TimePickerTwelveHours() {
  return (
    <div className="leaf-demo-stack">
      <TimePicker aria-label="12小时制" use12Hours defaultValue="14:30" />
      <TimePicker
        aria-label="精确到秒"
        use12Hours
        showSeconds
        secondStep={10}
        defaultValue="00:05:30"
      />
    </div>
  );
}

TimePicker API

属性	类型	默认值	说明
`value` / `defaultValue`	`string \| null`	`null`	`HH:mm` 格式的受控值 / 初始值
`onChange`	`(value: string \| null) => void`	—	确认选择时返回 HH:mm，清除时返回 null
`minuteStep`	`number`	`5`	分钟间隔，使用 1–60 的整数
`secondStep`	`number`	`1`	秒间隔，使用 1–60 的整数
`showSeconds`	`boolean`	`false`	显示秒选项，值使用 HH:mm:ss
`use12Hours`	`boolean`	`false`	展示 12 小时制及上午、下午选项
`allowClear`	`boolean`	`true`	展示清除按钮
`placeholder`	`string`	`'请选择时间'`	未选择时的提示文字
`size`	`'sm' \| 'md' \| 'lg'`	`'md'`	选择器尺寸
`status`	`'error' \| 'warning'`	—	校验状态
`disabled`	`boolean`	`false`	禁用整个控件
`name` / `form`	`string`	—	字段名 / 关联的表单 ID
`required`	`boolean`	`false`	要求选择时间
`onOpenChange`	`(open: boolean) => void`	—	面板展开或收起
`ref`	`Ref<HTMLInputElement>`	—	输入框引用

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

类型

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

import type { TimePickerProps, ControlSize, ControlStatus } from '@sudden3/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 放弃未确认内容。

#TimePicker 时间选择器

#基础选择

#受控与分钟间隔

#12 小时制与秒

#TimePicker API

#类型