TimePicker 时间选择器

用于选择或输入任意时间点的时间选择器，支持时/分/秒滚轮选择、12/24 小时制、禁用时间等高级功能。

TimePicker vs TimeSelect

• TimePicker: 通过滚轮面板自由选择任意时间点（本组件）
• TimeSelect: 从预设的固定时间列表中选择，适用于预约场景

根据业务需求选择合适的组件。

基础用法

点击输入框打开时间选择面板，通过滚动或点击选择时/分/秒。

当前值: 未选择

基础用法

禁用状态

使用 disabled 属性禁用整个时间选择器。

禁用状态

可清空

设置 clearable 属性可以清空已选时间。

当前值: 09:15:30

可清空

不同尺寸

使用 size 属性改变时间选择器大小，可选值为 large、default、small。

不同尺寸

12 小时制

设置 use12-hours 属性启用 12 小时制（AM/PM）。

当前值: 未选择

12 小时制

隐藏秒选择器

设置 show-seconds 为 false 可以隐藏秒选择列。

当前值: 未选择

隐藏秒选择器

箭头控制模式

设置 arrow-control 属性使用上下箭头控制时间，而非滚动列表。

箭头控制模式

步长设置

通过 hour-step、minute-step、second-step 属性设置时/分/秒的选择步长。

小时步长: 2, 分钟步长: 15, 秒步长: 30

步长设置

禁用时间

通过 disabled-time 属性配置禁用的时间，支持分别禁用小时、分钟、秒。

禁用: 0-5点, 22-23点, 12点的0/15/30/45分

禁用时间

时间范围选择

设置 is-range 属性启用时间范围选择模式。

至

当前值: 未选择

时间范围选择

时间范围自动排序

通过设置 order-on-confirm 属性为 true，系统将不再启用严格的禁用约束（即可以选择任意时间），而是在点击“确定”时如果发现时间顺序不对，自动进行交换处理。

至

当前值: 10:00:00 - 08:00:00

时间范围自动排序

完整功能演示

展示时间选择器的所有常用功能：可清空、底部操作栏、"此刻"按钮等。

完整功能演示

在 Nuxt 中使用

TimePicker 组件完全支持 Nuxt 3/4 的 SSR 渲染。在 Nuxt 项目中使用时，组件会自动导入。

Nuxt 中使用

SSR 注意事项：

• ✅ 组件结构和样式完全支持 SSR
• ✅ 初始值在服务端正确渲染
• ✅ 面板通过 Teleport 渲染，兼容 SSR 首屏
• ⚠️ 滚轮滚动定位在客户端激活后生效
• ⚠️ DOM 操作（如 focus）仅在客户端执行

SSR 最佳实践

TimePicker 的核心逻辑已针对 SSR 进行优化，所有可能导致 Hydration Mismatch 的操作（如时间戳生成、DOM 操作）都被安全地延迟到客户端执行。

API

Props

属性名	说明	类型	默认值
model-value / v-model	绑定值	string | Date | number | [string, string]	—
disabled	是否禁用	boolean	false
editable	是否可编辑	boolean	true
clearable	是否可清空	boolean	true
size	输入框尺寸	'large' | 'default' | 'small'	'default'
placeholder	占位文本	string	'选择时间'
start-placeholder	范围选择时开始的占位文本	string	'开始时间'
end-placeholder	范围选择时结束的占位文本	string	'结束时间'
is-range	是否为范围选择	boolean	false
format	时间格式	string	'HH:mm:ss'
value-format	绑定值的格式	string	'HH:mm:ss'
use12-hours	是否使用 12 小时制	boolean	false
show-seconds	是否显示秒选择器	boolean	true
hour-step	小时步长	number	1
minute-step	分钟步长	number	1
second-step	秒步长	number	1
disabled-time	禁用的时间配置	DisabledTimeConfig	—
popper-class	下拉框类名	string	—
teleported	是否将下拉框插入到 body	boolean	true
range-separator	范围分隔符	string	'-'
arrow-control	是否使用箭头控制	boolean	false
order-on-confirm	范围选择时，如果结束时间早于开始时间，是否自动交换	boolean	false
show-footer	是否显示底部操作栏	boolean	true
show-now	是否显示"此刻"按钮	boolean	true
confirm-text	确认按钮文本	string	'确定'
cancel-text	取消按钮文本	string	'取消'
now-text	此刻按钮文本	string	'此刻'
validate-event	是否触发表单验证	boolean	true

DisabledTimeConfig

属性名	说明	类型
disabledHours	禁用的小时	() => number[]
disabledMinutes	禁用的分钟（基于选中的小时）	(hour: number) => number[]
disabledSeconds	禁用的秒（基于选中的小时和分钟）	(hour: number, minute: number) => number[]

Events

事件名	说明	回调参数
change	时间变化时触发	(value: TimeValue | TimeRangeValue) => void
focus	获取焦点时触发	(event: FocusEvent) => void
blur	失去焦点时触发	(event: FocusEvent) => void
clear	清空时触发	() => void
visible-change	面板显示/隐藏时触发	(visible: boolean) => void
confirm	点击确认按钮时触发	(value: TimeValue | TimeRangeValue) => void
cancel	点击取消按钮时触发	() => void

Slots

插槽名	说明
prefix	自定义前缀图标
suffix	自定义后缀图标
range-separator	自定义范围分隔符

Expose

名称	说明	类型
focus	使选择器获取焦点	() => void
blur	使选择器失去焦点	() => void
open	打开选择面板	() => void
close	关闭选择面板	() => void

主题变量

所有颜色变量已与全局主题系统对接，自动支持暗黑模式：

变量名	说明	默认值
--yh-time-picker-width	选择器宽度	220px
--yh-time-picker-range-width	范围选择器宽度	360px
--yh-time-picker-active-color	高亮文字颜色	var(--yh-color-primary)
--yh-time-picker-active-bg	高亮背景颜色	var(--yh-color-primary-light-9)
--yh-time-picker-hover-bg	悬停背景颜色	var(--yh-fill-color-light)
--yh-time-picker-panel-bg	面板背景色	var(--yh-bg-color-overlay)
--yh-time-picker-panel-shadow	面板阴影	var(--yh-shadow-lg)
--yh-time-picker-text-color	文字颜色	var(--yh-text-color-primary)
--yh-time-picker-text-secondary	次要文字颜色	var(--yh-text-color-secondary)
--yh-time-picker-border	边框颜色	var(--yh-border-color-light)
--yh-time-picker-item-height	选项高度	32px
--yh-time-picker-spinner-height	滚轮高度	192px
--yh-time-picker-border-radius	圆角大小	var(--yh-border-radius-base)