vue-devui DatePickerPro 日期选择器实战指南:从基础用法到源码原理
vue-devui DatePickerPro 日期选择器实战指南:从基础用法到源码原理
DatePickerPro 是 vue-devui 组件库中面向"输入或选择日期"场景的高阶日期选择器组件,包含单日期选择器 DDatePickerPro 与范围日期选择器 DRangeDatePickerPro 两套组件,支持日期/年/月三种选择粒度、时分秒时间联动、自定义面板插槽与日历范围控制。本文以官方组件文档为核心骨架,结合仓库源码(date-picker-pro 组件目录)逐层拆解每个配置项的作用与底层实现,读完你可以直接照着 Demo 落地一个可用的日期选择场景,并理解其"虚拟滚动日历面板 + FlexibleOverlay 弹层 + Form 表单联动"的设计原理。
组件定位与注册方式
DatePickerPro 属于"数据录入"类组件,在组件入口 date-picker-pro/index.ts 中同时导出并注册了 DDatePickerPro 与 DRangeDatePickerPro 两个组件:
export { DatePickerPro, DRangeDatePickerPro };
export default {
title: 'DatePickerPro 日期选择器',
category: '数据录入',
status: '50%',
install(app: App): void {
app.component(DatePickerPro.name, DatePickerPro);
app.component(DRangeDatePickerPro.name, DRangeDatePickerPro);
},
};
其中 DatePickerPro.name 为 'DDatePickerPro',范围组件名为 'DRangeDatePickerPro'(见 date-picker-pro.tsx 与 range-date-picker-pro.tsx)。使用场景遵循官方文档:当用户需要输入一个日期时;需要点击标准输入框,弹出日期面板进行选择时。
基本用法:三种尺寸
DDatePickerPro 通过 v-model 双向绑定选中值,通过 size 控制输入框尺寸(sm / md / lg),默认尺寸为 md。
<template>
<div class="picker-pro-format-demo mr30">
<div class="mb10">Small</div>
<d-date-picker-pro v-model="datePickerProValue" class="mb20 wh250" size="sm" />
</div>
<div class="picker-pro-format-demo mr30">
<div class="mb10">Middle</div>
<d-date-picker-pro v-model="datePickerProValue2" class="mb20 wh250" />
</div>
<div class="picker-pro-format-demo mr30">
<div class="mb10">Large</div>
<d-date-picker-pro v-model="datePickerProValue3" class="mb20 wh250" size="lg" />
</div>
</template>
<script lang="ts">
import { defineComponent, ref } from 'vue';
export default defineComponent({
setup() {
const datePickerProValue = ref<string>('');
const datePickerProValue2 = ref<string>('');
const datePickerProValue3 = ref<string>('');
return {
datePickerProValue,
datePickerProValue2,
datePickerProValue3,
};
},
});
</script>
<style>
.mb20 {
margin-bottom: 20px;
}
.wh250 {
width: 250px;
}
</style>
从源码看,size 的默认值与类型在 date-picker-pro-types.ts 的公共属性中定义,且支持 Form 上下文覆盖:usePickerPro 中 pickerSize = computed(() => formContext?.size || props.size),也就是说当组件被放入 DForm / DFormItem 时,会优先继承表单统一设置的尺寸。
显示时间:showTime 与时分秒联动
设置 :showTime="true" 后,日历面板右侧会联动出现时分秒时间选择区,此时需要配合 format 声明含时间的格式:
<template>
<d-date-picker-pro v-model="datePickerProValue1" class="mb20 wh250" :showTime="true" format="YYYY/MM/DD HH:mm:ss" />
</template>
<script lang="ts">
import { defineComponent, ref } from 'vue';
export default defineComponent({
setup() {
const datePickerProValue1 = ref<string>('');
return {
datePickerProValue1,
};
},
});
</script>
时间格式的默认值
format 的默认值会根据是否开启 showTime 自动切换,这一逻辑在 use-picker-pro.ts 中实现:
const format = computed(() => {
return props.showTime ? props.format || DEFAULT_TIME : props.format || DEFAULT_DATE;
});
对应的默认常量定义在 const.ts:
export const DEFAULT_DATE = 'YYYY/MM/DD';
export const DEFAULT_TIME = `${DEFAULT_DATE} HH:mm:ss`;
即不传 format 时:未开启 showTime 默认显示 YYYY/MM/DD,开启后默认 YYYY/MM/DD HH:mm:ss。
日期与时间的合并逻辑
当同时选择日期和时间时,底层通过 use-date-picker.ts 的 getSelectedDate 把日历选中的日期与时间面板选中的时分秒合并:
const getSelectedDate = (date: Dayjs) => {
// 日期加上时间
const curDate = date.toDate().toLocaleDateString();
const curDateTime = `${curDate} ${timeData.value || '00:00:00'}`;
return dayjs(curDateTime).locale('zh-cn');
};
如果只选了日期未选时间,默认补 00:00:00;时间面板在 time-picker-panel.tsx 中渲染,时/分/秒三个列表的数据由 use-time-picker-panel.ts 基于 time-picker 的 initializeTimeData 初始化(小时 0-23、分钟/秒 0-59),复用 popup-line 作为滚动选择列表。测试用例 date-picker-pro.spec.tsx 专门校验了三个列表的渲染数量(24 / 60 / 60)。
自定义日历面板区域:rightArea 与 footer 插槽
日历面板提供两个插槽用于高度定制:rightArea 定制面板右侧内容(例如放置日期快捷选项),footer 定制面板下侧内容(例如放置"今天""清除时间"按钮):
<template>
<div class="mb10">right area</div>
<d-date-picker-pro v-model="datePickerProValue1" class="mb20 wh250" :showTime="true">
<template #rightArea>
<slot name="rightArea">
<ul class="date-picker-right-panel">
<li>
<d-button
variant="text"
color="primary"
@click="
() => {
setDate(-30);
}
"
>
一个月前
</d-button>
<span>{{ getDateString(-30) }}</span>
</li>
<li>
<d-button
variant="text"
color="primary"
@click="
() => {
setDate(-14);
}
"
>
两周前
</d-button>
<span>{{ getDateString(-14) }}</span>
</li>
<li>
<d-button
variant="text"
color="primary"
@click="
() => {
setDate(-7);
}
"
>
一周前
</d-button>
<span>{{ getDateString(-7) }}</span>
</li>
<li>
<d-button
variant="text"
color="primary"
@click="
() => {
setDate(0);
}
"
>
今天
</d-button>
<span>{{ getDateString(0) }}</span>
</li>
</ul>
</slot>
</template>
</d-date-picker-pro>
<div class="mb10">footer</div>
<d-date-picker-pro v-model="datePickerProValue2" class="mb20 wh250" :showTime="true">
<template #footer>
<slot name="footer">
<div class="date-picker-footer">
<d-button variant="solid" color="secondary" @click="setToday"> 今天 </d-button>
<d-button variant="solid" color="secondary" @click="clearDate"> 清除时间 </d-button>
</div>
</slot>
</template>
</d-date-picker-pro>
</template>
<script lang="ts">
import { defineComponent, ref } from 'vue';
export default defineComponent({
setup() {
const datePickerProValue1 = ref<string | Date>('');
const datePickerProValue2 = ref<string | Date>('');
const setDate = (days: number) => {
datePickerProValue1.value = new Date(new Date().getTime() + days * 24 * 3600 * 1000);
};
const getDateString = (days: number) => {
const date = new Date(new Date().getTime() + days * 24 * 3600 * 1000);
return `${date.getMonth() + 1}月${date.getDate()}日`;
};
const setToday = () => {
datePickerProValue2.value = new Date(new Date().getTime());
};
const clearDate = () => {
datePickerProValue2.value = '';
};
return {
datePickerProValue1,
datePickerProValue2,
setDate,
getDateString,
setToday,
clearDate,
};
},
});
</script>
<style>
.date-picker-right-panel {
padding: 0;
li {
list-style-type: none;
button {
width: 66px;
}
span {
margin-left: 8px;
}
}
}
.date-picker-footer {
display: flex;
justify-content: end;
button {
margin-left: 10px;
}
}
</style>
插槽在组件内部的落地位置
面板组件 date-picker-panel.tsx 是插槽的实际消费方:
{ctx.slots?.rightArea && <div class={ns.e('panel-right-area')}>{ctx.slots?.rightArea()}</div>}
...
{ctx.slots?.footer && <div class={ns.e('panel-footer')}>{ctx.slots?.footer()}</div>}
{!ctx.slots?.footer && props.showTime && (
<div class={ns.e('panel-footer')}>
<div class={ns.e('panel-footer-center')}>
<Button variant="solid" onClick={handlerConfirm}>{t('ok')}</Button>
</div>
</div>
)}
需要注意两个细节:
rightArea插槽渲染在面板内容区的右侧(panel-right-area),footer渲染在面板底部(panel-footer)。- 若未提供
footer插槽且开启了showTime,组件会自动渲染一个"确定"按钮,点击后触发handlerConfirm完成时间确认并关闭面板;提供footer插槽后则由插槽内容完全接管底部区域。
此外,两个插槽在单日期与范围组件中都通过 renderSlot 透传(见 date-picker-pro.tsx 与 range-date-picker-pro.tsx)。测试 date-picker-pro.spec.tsx 分别验证了 rightArea 中按钮点击后输入框值变为"30 天前"、footer 中按钮点击后值变为当天。
日期格式:format 的完整标识表
通过 format 指定输入框显示的日期格式,例如 YYYY-MM-DD。完整格式标识如下:
| 标识 | 示例 | 描述 |
|---|---|---|
| YY | 22 | 年,两位数 |
| YYYY | 2022 | 年,四位数 |
| M | 1-12 | 月,从 1 开始 |
| MM | 01-12 | 月,两位数字 |
| MMM | Jan-Dec | 月,英文缩写 |
| D | 1-31 | 日 |
| DD | 01-31 | 日,两位数 |
| H | 0-23 | 24 小时 |
| HH | 00-23 | 24 小时,两位数 |
| h | 1-12 | 12 小时 |
| hh | 01-12 | 12 小时,两位数 |
| m | 0-59 | 分钟 |
| mm | 00-59 | 分钟,两位数 |
| s | 0-59 | 秒 |
| ss | 00-59 | 秒,两位数 |
<template>
<div class="picker-pro-format-demo mr30">
<div class="mb10">日期格式: YYYY-MM-DD</div>
<d-date-picker-pro v-model="pickerProFormatValue" class="mb20 wh250" format="YYYY-MM-DD" />
</div>
<div class="picker-pro-format-demo">
<div class="mb10">日期格式: YYYY-MM-DD HH:mm:ss</div>
<d-date-picker-pro v-model="pickerProFormatValue1" class="mb20 wh250" :showTime="true" format="YYYY-MM-DD HH:mm:ss" />
</div>
</template>
<script lang="ts">
import { defineComponent, ref } from 'vue';
export default defineComponent({
setup() {
const pickerProFormatValue = ref<string>('');
const pickerProFormatValue1 = ref<string>('');
return {
pickerProFormatValue,
pickerProFormatValue1,
};
},
});
</script>
<style>
.picker-pro-format-demo {
display: inline-block;
}
.mr30 {
margin-right: 20px;
}
.mb10 {
margin-bottom: 10px;
}
</style>
非法格式的兜底策略
从源码看,输入框展示的字符串由 utils.ts 的 formatDayjsToStr 生成,它会校验格式化结果是否为合法日期,非法格式自动回退到默认格式:
export const formatDayjsToStr = (date: Dayjs | undefined, format: string, type: string): string | null => {
if (!date) {
return null;
}
if (type === 'year') {
return date.year().toString();
} else if (type === 'month') {
const month = date.month() + 1 < 10 ? '0' + (date.month() + 1) : date.month() + 1;
return `${date.year()}-${month}`;
} else {
// 兼容非法格式(format),如果是非法格式,则使用默认格式(YYYY/MM/DD)
return dayjs(date.format(format)).isValid() ? date.format(format) : date.format(DEFAULT_DATE);
}
};
年月选择器:type 指定选择粒度
通过 type 指定选择器类型,可选 date / year / month,默认 date。当类型为 year 时输入框只展示年份(如 2022),为 month 时展示 YYYY-MM(如 2022-01):
<template>
<div class="picker-pro-format-demo mr30">
<div class="mb10">year picker</div>
<d-date-picker-pro v-model="pickerProFormatValue" class="mb20 wh250" type="year" />
<div class="mb10">month picker</div>
<d-date-picker-pro v-model="pickerProFormatValue1" class="mb20 wh250" type="month" />
</div>
</template>
<script lang="ts">
import { defineComponent, ref } from 'vue';
export default defineComponent({
setup() {
const pickerProFormatValue = ref<string>('');
const pickerProFormatValue1 = ref<string>('');
return {
pickerProFormatValue,
pickerProFormatValue1,
};
},
});
</script>
三种面板的分派逻辑
type 决定面板组件渲染哪一种日历,分派逻辑在 date-picker-panel.tsx:
type === 'date'→CalendarPanel(日期日历面板),若showTime再叠加TimerPickerPanel;type === 'year'→YearCalendarPanel(纯年份滚动面板);type === 'month'→MonthCalendarPanel(左侧年份 + 右侧 12 个月网格)。
年/月面板同样基于 VirtualList 虚拟滚动渲染(高度常量见 const.ts:年选择器列表高 yearPickerHeight = 186、单行高 yearCalendarItemHeight = 48;月选择器列表高 monthPickerHeight = 300、单行高 monthCalendarItemHeight = 186)。对应的测试 year-picker.spec.tsx 覆盖了年份选择、v-model 回显以及 calendarRange / limitDateRange 对年份的禁用控制。
范围选择器:DRangeDatePickerPro
DRangeDatePickerPro 提供开始/结束日期范围选择,v-model 绑定 [Date, Date] 形式的二元数组(源码中类型为 (Date | string)[],默认 ['', ''])。它支持与单日期选择器一致的 showTime、format、type、separator 等配置:
<template>
<div class="mb10">basic range picker</div>
<d-range-date-picker-pro v-model="rangeDatePickerProValue" class="mb20" />
<div class="mb10">time range picker</div>
<d-range-date-picker-pro v-model="rangeDatePickerProValue1" class="mb20" :showTime="true" format="YYYY/MM/DD HH:mm:ss" />
<div class="mb10">year range picker</div>
<d-range-date-picker-pro v-model="rangeDatePickerProValue2" class="mb20 wh250" type="year" />
<div class="mb10">month range picker</div>
<d-range-date-picker-pro v-model="rangeDatePickerProValue3" class="mb20 wh250" type="month" />
</template>
<script lang="ts">
import { defineComponent, ref } from 'vue';
export default defineComponent({
setup() {
const rangeDatePickerProValue = ref<string[]>(['', '']);
const rangeDatePickerProValue1 = ref<string[]>(['', '']);
const rangeDatePickerProValue2 = ref<string[]>(['', '']);
const rangeDatePickerProValue3 = ref<string[]>(['', '']);
return {
rangeDatePickerProValue,
rangeDatePickerProValue1,
rangeDatePickerProValue2,
rangeDatePickerProValue3,
};
},
});
</script>
focusType:开始/结束输入框的焦点切换
范围组件的核心交互由 focusType(取值 start / end)驱动,实现在 use-range-date-picker-pro.ts:
- 点击开始输入框 →
onFocus('start');点击结束输入框 →onFocus('end');面板未打开时点击任意输入框统一重置为start。 - 选中开始日期后,日历选中逻辑会自动调用
changeRangeFocusType把焦点切到end,让用户继续选择结束日期(见 use-date-picker.ts 的handlerConfirm与 use-calendar-selected.ts 的emitSelectedDate)。 - 范围选择默认时间行为:开始日期补
00:00:00,结束日期补23:59:59(use-date-picker.ts)。 - 未开启
showTime时,开始、结束两个日期都选中后自动关闭面板。
separator 用于定义开始与结束输入框之间的分割符,默认 '-'(在 range-date-picker-types.ts 中声明,渲染于 range-date-picker-pro.tsx)。
自定义日期范围面板区域
范围选择器同样支持 rightArea 与 footer 插槽。右侧区域适合放置"一个月前""当前周"等范围快捷选项,底部可放置"清除开始时间""清除结束时间"等操作按钮:
<template>
<div class="mb10">right area</div>
<d-range-date-picker-pro v-model="datePickerProValue1" class="mb20 wh250" :showTime="true">
<template #rightArea>
<slot name="rightArea">
<ul class="date-picker-right-panel">
<li>
<d-button
variant="text"
color="primary"
@click="
() => {
setDate(-30);
}
"
>
一个月前
</d-button>
</li>
<li>
<d-button
variant="text"
color="primary"
@click="
() => {
setDate(-14);
}
"
>
一周前
</d-button>
</li>
<li>
<d-button
variant="text"
color="primary"
@click="
() => {
selectThisWeek();
}
"
>
当前周
</d-button>
</li>
</ul>
</slot>
</template>
</d-range-date-picker-pro>
<div class="mb10">footer</div>
<d-range-date-picker-pro ref="footerCustom" v-model="datePickerProValue2" class="mb20 wh250" :showTime="true">
<template #footer>
<slot name="footer">
<div class="date-picker-footer">
<d-button variant="solid" color="secondary" @click="clearStartDate"> 清除开始时间 </d-button>
<d-button variant="solid" color="secondary" @click="clearEndDate"> 清除结束时间 </d-button>
</div>
</slot>
</template>
</d-range-date-picker-pro>
</template>
<script lang="ts">
import { defineComponent, ref } from 'vue';
export default defineComponent({
setup() {
const datePickerProValue1 = ref<string | Date[]>(['', '']);
const datePickerProValue2 = ref<string | Date[]>(['', '']);
const setDate = (days: number) => {
datePickerProValue1.value = [new Date(new Date().getTime() + days * 24 * 3600 * 1000), new Date()];
};
const selectThisWeek = () => {
const tody = new Date();
const start = new Date(new Date().setDate(tody.getDate() - tody.getDay()));
const end = new Date(new Date().setDate(start.getDate() + 6));
datePickerProValue1.value = [start, end];
};
const footerCustom = ref();
const clearStartDate = () => {
const [start, end] = datePickerProValue2.value;
datePickerProValue2.value = ['', end];
footerCustom?.value.focusChange('start');
};
const clearEndDate = () => {
const [start, end] = datePickerProValue2.value;
datePickerProValue2.value = [start, ''];
footerCustom?.value.focusChange('end');
};
return {
datePickerProValue1,
datePickerProValue2,
setDate,
selectThisWeek,
footerCustom,
clearStartDate,
clearEndDate,
};
},
});
</script>
通过实例方法 focusChange 控制焦点
上面 Demo 中通过 ref="footerCustom" 拿到范围组件实例并调用 focusChange('start' | 'end') 手动切换输入框焦点。该能力来自范围组件通过 ctx.expose 暴露的实例方法:
ctx.expose({
focusChange: onChangeRangeFocusType,
});
见 use-range-date-picker-pro.ts,onChangeRangeFocusType 内部会更新 focusType 并自动 focus() 对应输入框,非常适合在自定义 footer 中配合"清除开始/结束时间"这类局部清空操作使用。
禁用选择器
通过 :disabled="true" 禁用选择器,禁用后输入框不可交互、无法弹出日历面板:
<template>
<d-date-picker-pro v-model="datePickerProValue1" class="mb20 wh250 mr30" :disabled="true" />
<d-range-date-picker-pro v-model="datePickerProValue2" class="mb20 wh250" :disabled="true" />
</template>
<script lang="ts">
import { defineComponent, ref } from 'vue';
export default defineComponent({
setup() {
const datePickerProValue1 = ref<string>('');
const datePickerProValue2 = ref<string[]>(['', '']);
return {
datePickerProValue1,
datePickerProValue2,
};
},
});
</script>
禁用状态同样支持表单联动:usePickerPro 中 pickerDisabled = computed(() => formContext?.disabled || props.disabled),即 Form 设置 disabled 时组件自动禁用。范围组件禁用后会为容器附加 disabled 修饰类(range-date-picker-pro.tsx)。对应测试见 date-picker-pro.spec.tsx,禁用后 focus 不再弹出面板。
设置日历面板可选时间范围:calendarRange 与 limitDateRange
calendarRange:设置日历面板显示的时间范围,类型[number, number](起始年、结束年),默认[1970, 2099]。它决定左侧年份虚拟列表与中间月份日历的渲染跨度。limitDateRange:设置日历面板可选择的时间范围,类型[Date, Date],默认取[new Date(calendarRange[0]), new Date(calendarRange[1])],范围外的日期置灰不可点选。
<template>
<d-date-picker-pro v-model="datePickerProValue1" class="mb20 wh250 mr30" :calendarRange="[2022, 2025]" :limitDateRange="limitDateRange" />
<d-range-date-picker-pro
v-model="datePickerProValue2"
class="mb20 wh250"
:calendarRange="[2022, 2025]"
:limitDateRange="limitDateRange"
/>
</template>
<script lang="ts">
import { defineComponent, ref } from 'vue';
export default defineComponent({
setup() {
const datePickerProValue1 = ref<string>('');
const datePickerProValue2 = ref<string[]>(['', '']);
const limitDateRange = ref<Date[]>([new Date(2022, 1, 5), new Date(2023, 1, 5)]);
return {
datePickerProValue1,
datePickerProValue2,
limitDateRange,
};
},
});
</script>
两个范围的底层换算
use-calendar-selected.ts 中,limitDateRange 会被换算为 minDate / maxDate:
const minDate = computed(() => {
if (props.limitDateRange && props.limitDateRange[0]) {
return props.limitDateRange[0];
} else {
return new Date(calendarRange.value[0], 0, 1);
}
});
const maxDate = computed(() => {
if (props.limitDateRange && props.limitDateRange[1]) {
return props.limitDateRange[1];
} else {
return new Date(calendarRange.value[1], 11, 31);
}
});
日期的禁用判断 isDisabled 在 use-calendar-panel.ts 中实现,只有落在 <a href="https://link.gitcode.com/i/c76aa948d89814926dccc5d6ff8ca066" target="_blank">minDate, maxDate] 闭区间内的日期可点选;年/月选择器同样基于该范围计算禁用状态(见 [year-picker.spec.tsx)。日历数据的初始化(按年生成 12 个月、每个月的 6 行周数据)也在 use-calendar-panel.ts 完成,并对相同 calendarRange 的结果做了 Map 缓存,避免重复计算。
DatePickerPro API 参考
DatePickerPro 参数
| 参数名 | 类型 | 默认 | 说明 | 跳转 Demo |
|---|---|---|---|---|
| v-model | Date |
'' | 必选,选中项绑定的值 | 基本用法 |
| format | Format | 'YYYY/MM/DD' | 'YYYY/MM/DD HH:mm:ss' | 可选,绑定值的日期格式,根据是否 showTime 区别不同默认值 | 日期格式 |
| placeholder | string |
'请选择日期' | 可选,输入框的 placeholder | 基本用法 |
| showTime | boolean |
false | 可选,是否显示时分秒 | 显示时间 |
| size | string |
'md' | 可选,输入框的尺寸 | 基本用法 |
| disabled | boolean |
false | 可选,是否禁用选择器 | 禁用选择器 |
| calendarRange | [number,number] |
[1970, 2099] | 可选,设置日历面板显示时间范围 | 设置日历面板可选时间范围 |
| limitDateRange | [Date,Date] |
[new Date(calendarRange[0]), new Date(calendarRange[1])] | 可选,设置日历面板可选时间范围 | 设置日历面板可选时间范围 |
| type | string |
'date' | 可选,设置日期选择器类型(date/year/month) | 年月选择器 |
| show-glow-style | boolean |
true | 可选,是否显示悬浮发光效果 | |
| position | Placement[] | ['bottom-start','top-start'] | 可选,自定义下拉面板位置 |
DatePickerPro 事件
| 事件名 | 类型 | 说明 | 跳转 Demo |
|---|---|---|---|
| toggleChange | (bool: boolean) => void |
可选,选择器打开关闭 toggle 事件 | |
| confirmEvent | (date: Date) => void |
可选,用户确定选定的值时触发 | |
| focus | (e: MouseEvent) => void |
可选,输入框获取焦点时触发 | |
| blur | () => void |
可选,输入框失去焦点时触发 |
DatePickerPro 插槽
| 名称 | 说明 | 跳转 Demo |
|---|---|---|
| rightArea | 自定义 DatePickerPro 日历面板右侧内容, 如:日期快捷选项 | 自定义日历面板区域 |
| footer | 自定义 DatePickerPro 日历面板下侧内容 | 自定义日历面板区域 |
DatePickerPro 类型定义
Format
type Format = string;
日期格式 format 支持的标识列表见上文 日期格式:format 的完整标识表。
事件与闭合机制
从源码看,四个事件由 use-picker-pro.ts 统一派发:
- 输入框聚焦时调用
toggleChange(true)并 emitfocus; - 面板关闭(含点击外部关闭)时调用
toggleChange(false)并 emitblur; - 用户确定选中值时 emit
confirmEvent(参数为Date)并关闭面板; - 外部点击关闭通过
@vueuse/core的onClickOutside监听 overlay,ignore: [originRef]保证点击输入框本身不会误关闭。
另外,v-model 变化时会联动触发 formItemContext?.validate('change') 做表单校验;showGlowStyle 控制输入框的悬浮发光效果;position 传入 FlexibleOverlay 控制弹层方位,面板打开/关闭的淡入淡出动画方向(fade-top / fade-bottom)由实际位置计算得出(date-picker-pro.tsx)。
RangeDatePickerPro API 参考
RangeDatePickerPro 参数
| 参数名 | 类型 | 默认 | 说明 | 跳转 Demo |
|---|---|---|---|---|
| v-model | [Date, Date] |
['',''] | 必选,选中项绑定的值 | 范围选择器 |
| format | Format | 'YYYY/MM/DD' | 'YYYY/MM/DD HH:mm:ss' | 可选,绑定值的日期格式,根据是否 showTime 区别不同默认值 | 日期格式 |
| placeholder | Array |
['请选择开始日期', '请选择结束日期'] | 可选,输入框的 placeholder | 范围选择器 |
| showTime | boolean |
false | 可选,是否显示时分秒 | 范围选择器 |
| separator | string |
'-' | 可选,范围选择器的分割符 | 范围选择器 |
| size | string |
'md' | 可选,输入框的尺寸 | |
| disabled | boolean |
false | 可选,是否禁用选择器 | 禁用选择器 |
| calendarRange | [number,number] |
[1970,2099] | 可选,设置日历面板显示时间范围 | 设置日历面板可选时间范围 |
| limitDateRange | [Date,Date] |
[new Date(calendarRange[0]), new Date(calendarRange[1])] | 可选,设置日历面板可选时间范围 | 设置日历面板可选时间范围 |
| type | string |
'date' | 可选,设置日期选择器类型(date/year/month) | 范围选择器 |
| show-glow-style | boolean |
true | 可选,是否显示悬浮发光效果 | |
| position | Placement[] | ['bottom-start','top-start'] | 可选,自定义下拉面板位置 |
RangeDatePickerPro 事件
| 事件名 | 类型 | 说明 | 跳转 Demo |
|---|---|---|---|
| toggleChange | (bool: boolean) => void |
可选,选择器打开关闭 toggle 事件 | |
| confirmEvent | (date: Date[]) => void |
可选,用户确定选定的时间范围时触发 | |
| focus | (e: MouseEvent) => void |
可选,输入框获取焦点时触发 | |
| blur | () => void |
可选,输入框失去焦点时触发 |
RangeDatePickerPro 插槽
| 名称 | 说明 | 跳转 Demo |
|---|---|---|
| rightArea | 自定义 RangeDatePickerPro 日历面板右侧内容, 如:日期范围快捷选项 | 自定义日期范围面板区域 |
| footer | 自定义 RangeDatePickerPro 日历面板下侧内容 | 自定义日期范围面板区域 |
类型定义
Placement
type Placement =
| 'top'
| 'right'
| 'bottom'
| 'left'
| 'top-start'
| 'top-end'
| 'right-start'
| 'right-end'
| 'bottom-start'
| 'bottom-end'
| 'left-start'
| 'left-end';
补充说明两个源码细节:
position的实际默认值:类型声明文件 date-picker-pro-types.ts 中position的默认值为['bottom-start', 'top-start', 'left-start', 'right-start'](比表格示例多了左右两个备选方位),传多个方位时 FlexibleOverlay 会按顺序自适应选择可用位置。placeholder的国际化兜底:单日期与范围组件的placeholderprop 默认值为空,未传时由createI18nTranslate('DDatePickerPro', app)从 locale 读取'请选择日期'/'请选择开始日期'/'请选择结束日期'(中文文案见 locale/lang/zh-cn.ts,英文见 locale/lang/en-us.ts),因此表格中的默认 placeholder 在跟随语言环境自动切换。
底层实现要点总结
最后汇总一下阅读本文所需的源码线索,便于进一步深入:
- 组件入口与注册:date-picker-pro/index.ts
- Props 声明(含全部默认值):date-picker-pro-types.ts、range-date-picker-types.ts
- 单日期交互逻辑:use-picker-pro.ts(聚焦/关闭/清空/表单联动)
- 范围交互逻辑:use-range-date-picker-pro.ts(focusType 切换、实例方法
focusChange) - 面板组装:date-picker-panel.tsx(按
type/showTime/ 插槽分派) - 日历数据与虚拟滚动:use-calendar-panel.ts、calendar-panel.tsx(左右双 VirtualList、缓存、滚动联动)
- 可选范围计算:use-calendar-selected.ts(
minDate/maxDate、范围修正fixRangeDate) - 日期时间合成:use-date-picker.ts
- 格式化与解析:utils.ts、const.ts
- 测试用例:date-picker-pro.spec.tsx、range-date-picker-pro.spec.tsx、year-picker.spec.tsx、month-picker.spec.tsx
结合以上内容,你可以快速在项目中使用 DDatePickerPro / DRangeDatePickerPro 完成单日期、时间联动、年月粒度、范围选择、快捷选项定制与禁用/范围限制等场景,并在需要深度定制时直接定位到对应的 composable 与面板组件源码。