日期选择器 DatePicker
选择日期的控件。
悄悄告诉你，DatePicker、TimePicker、DateTimePicker 里面很可能是很可能是同一个组件。
基础使用
传入 modelValue 进入受控模式。不传或者为 undefined 则为非受控模式，此时可以传入 defaultValue 属性作为默认值。
隐藏源代码
日期范围
隐藏源代码
年份选择
隐藏源代码
月份选择
隐藏源代码
季度选择
隐藏源代码
周选择
隐藏源代码
快速跳转
Date
隐藏源代码
自定义分隔符
TO
隐藏源代码
自定义格式化
通过 template 设置格式化模板。除此以外，还可以通过 format 和 parse 设置格式化和转化函数。当时间字符串解析失败时，组件将会保持输入之前的值。
隐藏源代码
更多配置
DatePicker 还拥有 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
DatePickerProps
| 属性 | 类型 | 可选 | 默认值 | 描述 | 版本 |
|---|---|---|---|---|---|
| modelValue | Date | Date[] | null | 是 | | 日期选择器的值（受控模式），支持 v-model。 | 0.2.0 |
| defaultValue | Date | Date[] | null | 是 | | 日期选择器的默认值（非受控模式）。 | 0.2.0 |
| mode | 'date' | 'date-range' | 'year' | 'year-range' | 'month' | 'month-range' | 'quarter' | 'quarter-range' | 'week' | 是 | 'date' | 日期选择的模式。 | 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 |
DatePickerEvents
| 事件 | 参数 | 描述 | 版本 |
|---|---|---|---|
| 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: MouseEvent | 通过下拉面板修改日期选择器值时的回调。 | 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 |
DatePickerSlots
| 插槽 | 参数 | 描述 | 版本 |
|---|---|---|---|
| prefix | | 前缀内容。 | 0.2.0 |
| suffix | | 后缀内容。 | 0.2.0 |
| splitter | | 范围选择时，分隔符的内容。 | 0.2.0 |
| quick | quickAccess: QuickAccessOption | 下拉面板的底部插槽。 | 0.2.0 |
DatePickerExpose
| 属性 | 类型 | 可选 | 默认值 | 描述 | 版本 |
|---|---|---|---|---|---|
| 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
ts
export type QuickAccessOption = {
label: string
key?: string | number | symbol
targetTime: Date | Date[] | (() => Date | Date[])
buttonProps?: ButtonProps
}NumberOrPercentage
ts
export type NumberOrPercentage = number | `${number}%`RestAttrs
ts
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
}