TimePicker
选择时间或时间范围。中文惯用名：时间选择器。
稳定本期新增已接入
元信息
| 字段 | 值 |
|---|---|
| 规范 ID | component.time-picker |
| 名称 | TimePicker |
| 二级分类 | 数据录入（data-entry） |
| 用途 | 选择时间或时间范围 |
| 描述 | 中文惯用名：时间选择器。 |
预览
静态结构：TimePicker 为 input 风格触发器（data-slot="timepicker-trigger"，右侧 Clock 图标）+ 受控 Popover 弹层（data-slot="timepicker-panel"）；弹层内为时 / 分（/秒）三列滚动列表（data-slot 分别为 timepicker-hour-column / timepicker-minute-column / timepicker-second-column，format 为 HH:mm 时无秒列），列内点选更新待选值；底部操作行左侧「此刻」（取当前时间）、右侧「确定」（提交并关闭）。Form 内声明 name 时外层包 FieldShell（label + 校验错误）。
DSL 结构
{
"type": "TimePicker",
"props": {
"name": "meetingTime",
"format": "HH:mm",
"placeholder": "请选择时间"
}
}何时用
何时使用
- 录入一天内的时间点：营业时间、预约时段、定时任务的执行时刻。
- format 为 HH:mm 时只需到分钟精度；含秒场景使用缺省 HH:mm:ss。
何时不用
- 选择日期或日期 + 时间：使用 DatePicker；TimePicker 不含日期维度。
- 选择时间区间（开始 - 结束）：当前实现为单时间点，区间用两个 TimePicker 字段或等待区间组件。
- 相对时长（如「30 分钟后」）：使用 NumberInput + 单位说明。
变体
| 变体 | 视觉形态 | 适用场景 |
|---|---|---|
| HH:mm:ss 含秒（缺省） | 时 / 分 / 秒三列，值形如 13:45:00 | 需要秒级精度的时刻（定时任务、日志时间） |
| HH:mm 无秒 | 时 / 分两列，值形如 13:45 | 常规业务时刻（营业时间、预约） |
| placeholder 空态 | 未选时触发器显示弱提示（缺省「请选择时间」） | 非必填时间字段 |
| disabled 禁用 | 触发器半透明不可点开 | 联动未就绪或只读场景 |
API 属性
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
name | string | — | 字段名；在 Form 内声明即自动成为表单项 |
label | string | — | 表单项标签（FieldShell 呈现） |
rules | FieldRule[] | — | 校验规则 |
value | string | — | 受控值（时间字符串，如 "13:45:00"）；Form 内作为字段初始值 |
format | `'HH:mm:ss' | 'HH:mm'` | 'HH:mm:ss' |
placeholder | string | '请选择时间' | 空态提示文案 |
disabled | boolean | false | 禁用触发器 |
onChange | (value: string) => void | — | 时间变化事件，传出按 format 格式化的时间字符串（DSL 语义值） |
className | string | — | 根节点 class（Form 内为 form-item 容器，独立渲染时为触发器） |
style | CSSProperties | — | 根节点内联样式（同 className 的挂载规则） |
使用规范
- 值始终为字符串（HH:mm:ss 或 HH:mm），落库与回显保持同一 format，不要混用。
- 弹层内点选只是待选值，「确定」才提交；「此刻」仅把待选值设为当前时间，仍需确定。
- 开始 / 结束时间用两个字段并在 rules 或提交逻辑中校验先后顺序，组件本身不做区间约束。
- 与 DatePicker 组合表示完整日期时间；不要把时间字符串拼接进日期字段自行解析。
- Form 内声明 name 走 FieldShell，label 与错误提示由表单统一管理。
正例
- ✓ 营业时间设置：两个 TimePicker（format HH:mm）分别录入开始 / 结束，提交时校验先后。
- ✓ 定时任务：缺省 HH:mm:ss 精确到秒，「此刻」快速填入当前时间后微调。
- ✓ Form 内声明 name + 必填 rules，未选时间提交时给出错误提示。
反例
- ✕ 用 TimePicker 选择日期（应使用 DatePicker）。
- ✕ 同一字段时而 HH:mm 时而 HH:mm:ss 回显，值格式不一致导致解析失败。
- ✕ 把两个独立时间字段硬拼成一个字符串存区间，失去校验与比较能力。
Design Token 映射
不适用：组件 tokenRefs 为空：样式 Token 数据尚未接入，三层映射（Primitive → Semantic → Component）待样式 Token 接入后回填。