TimePicker
时间选择器，单选 type=time，HH:mm:ss 三列滚动选择，受控/非受控；展示经 Intl.DateTimeFormat 本地化。支持 type=timeRange 范围选择、format 字符串控制列、value 字符串入参。
如何引入
import { TimePicker } from '@chenzy-design/svelte';基础时间选择
滚动列选择时、分、秒，onChange 返回 Date
12 小时制
use12Hours + format="hh:mm:ss A"，带 AM/PM 列
自定义格式
format 决定显示哪些列，如 "HH:mm" 仅时、分
format="HH:mm"，仅时、分两列
步长与禁用时段
minuteStep 步长 + disabledHours/hideDisabledOptions 限制可选范围
步长 5 分钟，禁用非工作时段，超出范围项隐藏
尺寸 / 状态 / 禁用
size、status、clearable、disabled 等触发器形态
small
large + 可清除
error 状态
禁用
时间范围
type=timeRange 选择起止时间
面板头部/底部
panelHeader、panelFooter 自定义面板顶部与底部内容
受控面板
受控 open + onOpenChange，用 Button 切换面板开合
自定义触发器
triggerRender 完全替换默认触发器渲染
禁用时段
disabledTime 按已选时间动态返回禁用规则，覆盖顶层 disabledHours/Minutes/Seconds
此刻按钮
showNow 控制面板底部「此刻」快捷按钮的显隐
关闭卸载
destroyOnClose 控制面板关闭时卸载还是保留浮层 DOM
前缀
prefix 在触发器前展示文本或图标
API 参考
TimePicker
Props
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
value | — | Date | string | [Date|string|null, Date|string|null] | null | undefined |
defaultValue | — | Date | string | [Date|string|null, Date|string|null] | null | null |
type | — | 'time'|'timeRange' | 'time' |
range | — | boolean | false |
format | — | string | undefined |
open | — | boolean | undefined |
defaultOpen | — | boolean | false |
placeholder | — | string | '请选择时间' |
size | — | 'small'|'default'|'large' | 'default' |
status | — | 'default'|'warning'|'error' | 'default' |
disabled | — | boolean | false |
clearable | — | boolean | true |
hourStep | — | number | 1 |
minuteStep | — | number | 1 |
secondStep | — | number | 1 |
showSecond | — | boolean | true |
use12Hours | — | boolean | false |
disabledHours | — | () => number[] | undefined |
disabledMinutes | — | (hour: number) => number[] | undefined |
disabledSeconds | — | (hour: number, minute: number) => number[] | undefined |
hideDisabledOptions | — | boolean | false |
showNow | 显示「此刻」快捷按钮 | boolean | true |
destroyOnClose | 关闭时卸载浮层 DOM；false 则首次打开后保留 | boolean | true |
locale | — | string | 'zh-CN' |
onChange | — | (v: (Date|null) | [Date|null, Date|null]) => void | undefined |
onOpenChange | — | (open: boolean) => void | undefined |
ariaLabel | — | string | undefined |
autoAdjustOverflow | 浮层溢出自动调整 | boolean | true |
autoFocus | 挂载时自动聚焦触发器 | boolean | false |
clearIcon | 自定义清除按钮图标 | Snippet | undefined |
showClear | 是否显示清除按钮（clearable 别名） | boolean | undefined |
dropdownClassName | 浮层 className | string | undefined |
dropdownMargin | 浮层溢出冗余 | number | { x?: number; y?: number } | undefined |
dropdownStyle | 浮层内联样式 | string | Record<string, string> | undefined |
focusOnOpen | 打开面板时自动聚焦第一列 | boolean | true |
getPopupContainer | 浮层挂载容器 | () => HTMLElement | undefined |
motion | 面板展开动画 | boolean | true |
panelHeader | 面板顶部自定义内容 | string | Snippet | undefined |
position | 浮层弹出位置 | string | 'bottomLeft' |
prefix | 触发器前缀内容 | string | Snippet | undefined |
rangeSeparator | 范围模式分隔符 | string | '~' |
scrollItemProps | 滚动列 item 属性透传 | Record<string, unknown> | undefined |
stopPropagation | 阻止浮层点击事件冒泡 | boolean | true |
zIndex | 浮层 z-index | number | 1030 |
onBlur | 触发器失焦 | (e: FocusEvent) => void | undefined |
onFocus | 触发器聚焦 | (e: FocusEvent) => void | undefined |
onChangeWithDateFirst | onChange 参数 dateFirst 模式 | boolean | false |
onClickOutSide | 点击外部触发 | (e: MouseEvent) => void | undefined |
disabledTime | 按当前已选时间返回禁用规则，覆盖顶层 disabledHours/Minutes/Seconds，未返回的字段回退顶层 | (date: Date) => { disabledHours?: () => number[]; disabledMinutes?: (h: number) => number[]; disabledSeconds?: (h: number, m: number) => number[] } | undefined |
panelFooter | 面板底部自定义内容（在"此刻"/"确定"按钮上方插入） | string | Snippet | undefined |
inputStyle | 输入框样式（透传到触发器 button） | string | Record<string, string> | undefined |
inputReadOnly | 输入框 readonly 属性（仅允许通过面板选择） | boolean | false |
triggerRender | 完全自定义触发器渲染 | Snippet<[{ value: Date | null; placeholder: string; open: boolean; disabled: boolean }]> | undefined |
borderless | 无边框模式 | boolean | false |
preventScroll | focus 时阻止滚动 | boolean | false |
Methods
| 属性 | 类型 | 说明 |
|---|---|---|
focus() | — | 命令式聚焦触发器（尊重 preventScroll，对齐 Semi） |
blur() | — | 命令式移除焦点（对齐 Semi） |
Accessibility
| ARIA role | dialog |
- 触发器 button aria-haspopup=dialog、aria-expanded、aria-controls 指向面板
- 面板 role=dialog；每列 role=listbox，项 role=option + aria-selected
- 禁用项 aria-disabled=true 且不可点击/键选；hideDisabledOptions 时从列移除
- 触发器 Enter/Space/↓ 打开；Esc 关闭；选项 Enter/Space 选择
- 12h 制额外 AM/PM 列；文案经 locale TimePicker.am/pm
- 打开时各列命令式 scrollIntoView 到选中项
- timeRange 模式：面板顶部 role=tablist 起止切换；确定从起跳到止
- format 字符串经 core parseFormatSpec 决定显示列与 12h（覆盖 showSecond/use12Hours）
设计变量
| 变量 | 默认值 | 用法 |
|---|---|---|
--cd-color-time-picker-range-panel-border | rgba(0, 0, 0, 0.1) | 时间选择器描边颜色 |
--cd-color-time-picker-range-picker-panel-split-border | var(--cd-color-border) | 时间选择器菜单分割线颜色 |