SepTimePicker 时间选择器组件 v1.2.0

核心能力 时分秒滚动选择 · 12/24h 制切换 · placement 上下智能翻转 · 箭头 + 滚轮 + 点击 + 拖动 四种选择方式 · v1.2 新增 时间边界 · 键盘导航 · 悬停预览 · 列标题 · 时间差 · valueFormat · 时区标注

1. 基础使用（HH:mm:ss / HH:mm / 占位符 / 初始值）

HTML 声明式标签
JS API 初始化

2. 12 小时制（use12Hours）

HTML 声明式标签
JS API 初始化

3. placement 上下智能翻转

说明：面板默认在输入框下方，当下方空间不足时自动翻转到上方，不支持左右 12 方位
HTML 声明式标签
JS API 初始化

4. allowClear 清除 / "此刻" 按钮 / onChange 回调

HTML 声明式标签
JS API 初始化
onChange 返回值：—

5. JS API 动态操作（setValue / getValue / open / close / clear / setState / subscribe）

JS API 初始化
当前 getValue()：—
subscribe 变更日志：—

6. getContainer 指定渲染容器

JS API 初始化

点击下方输入框，时间面板将渲染到蓝色虚线容器内（而非 document.body）

📦 自定义容器（getContainer）

7. 禁用时分秒（disabledHours / disabledMinutes / disabledSeconds）

HTML 声明式标签
JS API 初始化

8. 尺寸（size）与无边框（bordered）

HTML 声明式标签

9. 可编辑输入（editable）与自定义图标（prefixIcon / suffixIcon）

HTML 声明式标签

10. 隐藏"此刻"按钮（showNow）与自定义底部（renderExtraFooter）

JS API 初始化

11. 校验状态（status）+ 免确认即选（needConfirm）

HTML 声明式标签

12. 只读（readonly）+ 自定义类名（className / style）

JS API 初始化

13. 步进选择（hourStep / minuteStep / secondStep）

HTML 声明式标签

14. 独立控制显示列（showHour / showMinute / showSecond）

说明：format 与列显示解耦。即使 format 不包含某部分也可强制显示列，反之亦然
HTML 声明式标签

15. 默认打开值（defaultOpenValue）+ 自定义面板（panelRender）

JS API 初始化
说明：

16. 联动禁用 disabledMinutes(hour) / disabledSeconds(hour, minute)

JS API 初始化（选不同小时，分钟禁用列表联动变化）
  • disabledMinutes(hour)：根据当前选中小时动态返回禁用分钟数组
  • disabledSeconds(hour, minute)：根据当前小时+分钟动态返回禁用秒数组
  • 选 hour 后 min/sec 列自动刷新禁用态，sanitizeDate 自动跳过禁用项

17. selectableRange 可选时间段

JS API 初始化
  • 支持字符串 '09:00:00 - 18:00:00' 或数组 ['09:00:00', '18:00:00']
  • 内部自动转换为 disabledHours/Minutes/Seconds，与现有禁用逻辑融合

18. shortcuts 快捷选项

JS API 初始化
  • 数组项可为对象 { text, value } 或字符串
  • 点击快捷项直接设置时间并按 needConfirm 规则确认

19. hourStep / minuteStep / secondStep 函数形式

JS API 初始化（上班时间 10min 粒度，其余 5min）

20. TimeRangePicker 基础 — 声明式标签 + JS API 混合示例

JS API 初始化声明式 — 基础时间范围（默认 HH:mm:ss）
声明式 — 考勤打卡（HH:mm + need-confirm="false" 点选即生效）
声明式 — 快捷选项 shortcuts（上午/下午/全天）
JS API — 会议室预约（初值 09:00~10:00 + 此刻按钮 + 快捷 30m/1h/2h）
JS API — 排班时段（HH:mm + nowText='现在' + start hourStep=4 + end minuteStep=15）
JS API — 只读 + 自定义 className（灰色只读外观）

21. TimeRangePicker — 独立配置 + 快捷选项 + 步进

JS API 初始化start / end 独立步进（开始小时 step=2，结束分钟 step=15）
快捷选项 + 12h 制（分钟 step=5）
自动归一化（end 早于 start 自动交换）

22. minTime / maxTime 时间边界约束

JS API 初始化（限制 09:00:00 ~ 18:00:00，小于9点或大于18点的值不可选）
  • minTime / maxTime 自动生成 disabledHours / disabledMinutes / disabledSeconds
  • 与已有的 disabled 函数自动合并，逻辑正确叠加
  • 支持 setState({ minTime, maxTime }) 和对应 setter 方法

23. inputReadOnly 只读输入 + columnHeaders 列标题头

说明：inputReadOnly 让输入框不可编辑但仍可打开面板，columnHeaders 在每列顶部显示"时/分/秒"标题
JS API 初始化

24. changeOnScroll 滚轮调值 + valueFormat 返回值格式分离

说明：在输入框上滚动滚轮即可增减时间（默认调整小时），无需打开面板。valueFormat 控制 getValue() 返回格式
JS API 初始化
getValue() 返回：—

25. 键盘导航（↑↓←→ Tab Enter）+ 悬停预览

JS API 初始化 说明：面板打开后用键盘方向键导航，鼠标悬停列表项临时预览值
试一试：点击下方组件打开面板 → 用 ↑ ↓ 调值、← → 切换列、Enter 确认

26. TimeRangePicker — showDiff 时间差显示

JS API 初始化 说明：选择时间范围后自动在分隔符旁显示差值（如 3h 30m）
JS API — 会议室预约（带时间差）
JS API — 考勤（HH:mm + diff）

27. 时区标注（utcOffset / timezone）

说明：设 utcOffset 或 timezone 后，输入框右侧显示时区徽章（如 UTC+08:00），不做时间值转换，仅标识当前时区。不设 = 本地时区，徽章隐藏
HTML 声明式标签 — utcOffset 数字偏移（分钟）
HTML 声明式标签 — timezone 时区名称
JS API 初始化 — 动态切换时区
当前 getState().utcOffset：—

详细说明

组件定位

SepTimePicker 是一个企业级时间选择器，支持时分秒滚动选择、12/24h 制切换、移动端底部弹出面板，在交互和可访问性上做了增强。

列显示规则

  • 默认按 format 自动推断显示哪些列
  • 可通过 showHour / showMinute / showSecond 独立强制开/关某列
  • 列隐藏后 header 冒号自动适配，列表索引不会错乱

步进（Step）

  • hourStep 小时步进，默认 1，可用 2/3/4/6
  • minuteStep 分钟步进，默认 1，可用 5/10/15/30
  • secondStep 秒步进，默认 1，可用 5/10/15/30
  • 步进值能被 24/60 整除效果最佳

禁用时分秒

  • disabledHours() 返回禁用小时数组 [0..23]
  • disabledMinutes() 返回禁用分钟数组 [0..59]
  • disabledSeconds() 返回禁用秒数组 [0..59]
  • 禁用项显示 cursor: not-allowed，鼠标无法触发选中
  • hideDisabledOptions=true 可直接隐藏禁用项
  • 初始化 / setValue / 默认打开值时会自动跳过禁用值选最近可用值

确认与免确认

  • needConfirm=true（默认）：选择后不立即提交，点"确认"才生效
  • needConfirm=false（免确认即选）：点选列表 / 箭头 / AM·PM / "此刻" 都直接提交值并关闭面板
  • 面板底部"此刻 / 确认"按钮栏在免确认模式下自动隐藏

默认打开值

  • defaultOpenValue：当输入框为空时打开面板，面板默认选中此时间
  • 如果输入框已有值，打开面板仍以已有值为准

面板渲染

  • renderExtraFooter：在面板底部追加自定义 HTML
  • panelRender：完全接管面板 HTML，入参是默认面板字符串，返回自定义字符串
  • popupClassName / popupStyle 可在外层面板上叠加类名和样式

placement 定位

  • 支持 topLeft / top / bottomLeft / bottom 四种锚点
  • 桌面端自动智能翻转：下方空间不够 → 翻到上方
  • 移动端自动切换为底部弹出 + backdrop 遮罩

时区标注

  • utcOffset：UTC 偏移分钟数，如 480 = UTC+08:00、-300 = UTC-05:00
  • timezone：IANA 时区名，如 'Asia/Shanghai'，自动换算偏移
  • 两者均不设 = 本地时区，输入框不显示徽章
  • 不做时间值转换，仅右侧徽章标注当前时区

受控与非受控

  • 传入 value → 受控模式，外部驱动值
  • 只传 defaultValue → 非受控，内部自行管理
  • onChange(newValue, { hour, minute, second }) 值变化回调
  • onOpenChange(open) 面板开关回调
  • onSelect（选值时）/ onClear（清除时）

API 速查

setValue(v)getValue() setState({})getState() open()close() toggle()clear() focus()blur() subscribe(fn)destroy() getEl()getPanel()

测试断言