时间选择器 TimePicker

选择时间的控件。

悄悄告诉你，DatePicker、TimePicker、DateTimePicker 里面很可能是很可能是同一个组件。

基础使用

传入 modelValue 进入受控模式。不传或者为 undefined 则为非受控模式，此时可以传入 defaultValue 属性作为默认值。

隐藏源代码

范围选择

隐藏源代码

快速跳转

Single Value

Range

24 Hours

12 Hours

隐藏源代码

自定义分隔符

TO

隐藏源代码

自定义格式化

通过 template 设置格式化模板。除此以外，还可以通过 format 和 parse 设置格式化和转化函数。当时间字符串解析失败时，组件将会保持输入之前的值。

隐藏源代码

更多配置

TimePicker 还拥有 Input 组件的大部分功能。

Disabled, Readonly, Loading & Clearable

Shape

Size

Slot

prefix

suffix

Composite

Start:

Status

Expose

隐藏源代码

Formatter

组件支持基于正则表达式匹配的时间格式化模板，可通过下列模板字符解析时间字符串中的各个部分。

模板	匹配规则	说明
YYYY	(-?\d{4,6})	年份，支持 4 至 6 位数字，可包含负号（如公元前）
YY	(\d{2})	年份的后两位数字
MM	(\d{2})	月份，两位数字（01-12）
DD	(\d{2})	日期，两位数字（01-31）
HH	(\d{2})	小时（24小时制），两位数字（00-23）
hh	(\d{2})	小时（12小时制），两位数字（01-12）
mm	(\d{2})	分钟，两位数字（00-59）
ss	(\d{2})	秒钟，两位数字（00-59）
SSS	(\d{3})	毫秒，三位数字（000-999）
A	(AM|PM)	上下午标记，大写 AM 或 PM
ww	(\d{2})	周数，一年中的第几周，两位数字（01-53，遵循 ISO 周历规则）
Q	(\d{1})	季度，一位数字（1-4）

[] 中括号中的文本会被提取出来原样保留，例如 YYYY-[Q]Q 可以生成 2026-Q1，中括号中的 Q 被原样保留。

周的计算方式遵循 ISO 8601 标准，一周的开始是周一，每年的第一周是包含该年第一个周四的那一周。

API

TimePickerProps

属性	类型	可选	默认值	描述	版本
modelValue	Date | Date[] | null	是		时间选择器的值（受控模式），支持 v-model。	0.2.0
defaultValue	Date | Date[] | null	是		时间选择器的默认值（非受控模式）。	0.2.0
mode	'time' | 'time-range'	是	'time'	时间选择的模式。	0.2.0
use12Hours	boolean	是	false		0.2.0
placeholder	string	是		占位符文本。	0.2.0
placeholderStart	string	是		开始时间的占位符文本。	0.2.0
placeholderEnd	string	是		结束时间的占位符文本。	0.2.0
disabled	boolean	是	false	是否禁用。	0.2.0
readonly	boolean	是	false	是否只读。	0.2.0
clearable	boolean	是	false	是否显示清除按钮。	0.2.0
loading	boolean	是	false	是否显示加载状态。	0.2.0
template	string	是		日期格式化模板。	0.2.0
format	(time: Date) => string	是		日期格式化函数，优先于 template。	0.2.0
parse	(timeString: string) => Date	是		转化格式化字符串到时间的函数，优先于 template。	0.2.0
size	'medium' | 'large' | 'small'	是	'medium'	时间选择器输入框尺寸。	0.2.0
shape	'rect' | 'round'	是	'rect'	时间选择器输入框形状。	0.2.0
borderRadius	NumberOrPercentage | NumberOrPercentage[]	是		圆角半径，优先级高于 shape，与 CSS border-radius 行为一致；单值或长度为 1 的数组 → 四角同时生效；长度为 2 的数组 → [左上 & 右下, 右上 & 左下]；长度为 3 的数组 → [左上, 右上 & 左下, 右下]；长度为 4 的数组 → 按顺时针顺序依次作用于四角。	0.2.0
status	'success' | 'warning' | 'error' | 'normal'	是		表单验证状态。	0.2.0
autofocus	boolean	是	false	原生 <input> 的 autofocus 属性。	0.2.0
autofocusStart	boolean	是	false	开始日期的原生 <input> 的 autofocus 属性。	0.2.0
autofocusEnd	boolean	是	false	结束日期的原生 <input> 的 autofocus 属性。	0.2.0
dropdownDestroyOnHide	boolean	是	false	下拉选择面板是否会在隐藏时销毁。	0.2.0
pollSizeChange	boolean	是	false	开启轮询组件尺寸变化，可能会影响性能。	0.2.0
dropdownProps	Omit<PopoverProps, 'visible' | 'content'> & EmitEvent<PopoverEvents>	是		下拉选择面板的属性。	0.2.0
needDropdown	boolean	是	false	是否需要展示下拉选择面板。	0.2.0
quickAccess	QuickAccessOption[]	是		快速跳转按钮的选项。	0.2.0

TimePickerEvents

事件	参数	描述	版本
input	value: string, event: Event	时间选择器输入时的回调。	0.2.0
update:modelValue	value: Date | Date[] | null	更新 modelValue 的回调。	0.2.0
change	value: Date | Date[] | null, event?: Event	时间选择器值变化时的回调。	0.2.0
clear	value: Date | Date[] | null	点击清除文本按钮，清除内容时的回调。	0.2.0
blur	event: FocusEvent	时间选择器失焦时的回调。	0.2.0
focus	event: FocusEvent	时间选择器聚焦时的回调。	0.2.0
select	value: Date | Date[], event: Event	通过下拉面板修改时间选择器值时的回调。	0.2.0
dropdownOpen		下拉面板展示的回调。	0.2.0
dropdownClose		下拉面板关闭的回调。	0.2.0

TimePickerSlots

插槽	参数	描述	版本
prefix		前缀内容。	0.2.0
suffix		后缀内容。	0.2.0
splitter		范围选择时，分隔符的内容。	0.2.0
quick	quickAccess: QuickAccessOption	下拉面板的底部插槽。	0.2.0

TimePickerExpose

属性	类型	可选	默认值	描述	版本
focus	(placement?: 'start' | 'end') => void	否		聚焦当前控件，范围选择时不传 placement 默认作用于开始时间。	0.2.0
blur	(placement?: 'start' | 'end') => void	否		取消聚焦当前控件，范围选择时不传 placement 默认作用于开始时间。	0.2.0
clear	() => void	否		清空当前输入内容。	0.2.0
select	(placement?: 'start' | 'end') => void	否		选中当前输入内容，范围选择时不传 placement 默认作用于开始时间。	0.2.0

QuickAccessOption

export type QuickAccessOption = {
	label: string
	key?: string | number | symbol
	targetTime: Date | Date[] | (() => Date | Date[])
	buttonProps?: ButtonProps
}

NumberOrPercentage

export type NumberOrPercentage = number | `${number}%`

RestAttrs

import type { StyleValue } from 'vue'

export type VueClassValue = string | Record<string, any> | VueClassValue[]
export type VueStyleValue = StyleValue

export type RestAttrs = {
	style?: VueStyleValue | null
	class?: VueClassValue | null
	[x: string]: any
}