日期时间选择器 DateTimePicker

选择日期时间的控件。

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

基础使用

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

隐藏源代码

范围选择

隐藏源代码

快速跳转

Single Value

Range

24 Hours

12 Hours

隐藏源代码

自定义分隔符

TO

隐藏源代码

自定义格式化

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

隐藏源代码

更多配置

DateTimePicker 还拥有 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

DateTimePickerProps

属性	类型	可选	默认值	描述	版本
modelValue	Date | Date[] | null	是		日期时间选择器的值（受控模式），支持 v-model。	0.2.0
defaultValue	Date | Date[] | null	是		日期时间选择器的默认值（非受控模式）。	0.2.0
mode	'date-time' | 'date-time-range'	是	'date-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

DateTimePickerEvents

事件	参数	描述	版本
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
monthPrev	referredDate: Date, event: MouseEvent	日期选择面板中，月份向前移动的回调。	0.2.0
monthNext	referredDate: Date, event: MouseEvent	日期选择面板中，月份向后移动的回调。	0.2.0
yearPrev	referredDate: Date, event: MouseEvent	日期选择面板中，年份向前移动的回调。	0.2.0
yearNext	referredDate: Date, event: MouseEvent	日期选择面板中，年份向后移动的回调。	0.2.0
referredDateSelect	referredDate: Date, event: MouseEvent	日期选择面板中，通过年月的下拉选项选择年月时的回调。	0.2.0
referredDateChange	referredDate: Date, event: MouseEvent	日期选择面板中，年月改变的回调。	0.2.0
dropdownOpen		下拉面板展示的回调。	0.2.0
dropdownClose		下拉面板关闭的回调。	0.2.0

DateTimePickerSlots

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

DateTimePickerExpose

属性	类型	可选	默认值	描述	版本
focus	(placement?: 'start' | 'end') => void	否			0.2.0
blur	(placement?: 'start' | 'end') => void	否			0.2.0
clear	() => void	否			0.2.0
select	(placement?: 'start' | 'end') => void	否			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
}