Element (Vue 2) Date Picker 完整指南:从 type 体系、格式控制到 Range 面板的源码级解析
Element (Vue 2) Date Picker 完整指南:从 type 体系、格式控制到 Range 面板的源码级解析
Element(eleme/element)的 el-date-picker 是 Vue 2 生态中最常被使用的日期选择组件之一。本文基于仓库中文档 examples/docs/es/date-picker.md 的完整 API 与示例展开,并深入 packages/date-picker 源码,讲清 type 到面板组件的映射关系、format/value-format 的解析链路、picker-options 如何注入面板实例等底层机制,帮助你在业务中熟练完成"单日期、周/月/年多选、日期/月区间、快捷选项、禁用日期、时间戳绑定"等全部场景,并能读懂组件内部是如何把用户输入转换为 Date 对象的。
一、按天选择日期与 picker-options
最基础的用法是通过 type="date" 提供按天选择的输入框。组件的尺寸由 size 属性控制,而"快捷选项(shortcuts)"与"禁用日期(disabledDate)"则通过 picker-options 对象配置:shortcuts 是 { text, onClick } 对象数组,disabledDate 是一个接收 Date 参数、返回布尔值的函数。
<template>
<div class="block">
<span class="demonstration">Default</span>
<el-date-picker
v-model="value1"
type="date"
placeholder="Pick a day">
</el-date-picker>
</div>
<div class="block">
<span class="demonstration">Picker with quick options</span>
<el-date-picker
v-model="value2"
type="date"
placeholder="Pick a day"
:picker-options="pickerOptions">
</el-date-picker>
</div>
</template>
<script>
export default {
data() {
return {
pickerOptions: {
disabledDate(time) {
return time.getTime() > Date.now();
},
shortcuts: [{
text: 'Today',
onClick(picker) {
picker.$emit('pick', new Date());
}
}, {
text: 'Yesterday',
onClick(picker) {
const date = new Date();
date.setTime(date.getTime() - 3600 * 1000 * 24);
picker.$emit('pick', date);
}
}, {
text: 'A week ago',
onClick(picker) {
const date = new Date();
date.setTime(date.getTime() - 3600 * 1000 * 24 * 7);
picker.$emit('pick', date);
}
}]
},
value1: '',
value2: '',
};
}
};
</script>
源码印证:picker-options 是如何生效的。在 picker.vue 的 mountPicker 中,组件首次打开时会把 this.pickerOptions 的每个自有属性逐一赋值到内部 picker 实例上(selectableRange 除外,它会被单独解析为时间范围数组),并注册 this.$watch('pickerOptions', () => updateOptions(), { deep: true })——这意味着你在 data 中动态修改 pickerOptions(例如切换 disabledDate 函数)会在下一次面板挂载/更新时自动同步进去。而 shortcuts 的点击渲染位于 panel/date.vue:v-for 遍历 shortcuts 生成 el-picker-panel__shortcut 按钮,点击后调用 handleShortcutClick,最终由你在 onClick 里 $emit('pick', ...) 完成选值。disabledDate 则在 basic/date-table.vue 中被逐格调用:cell.disabled = typeof disabledDate === 'function' && disabledDate(cellDate)。
二、其他选择粒度:week / month / year / dates / months / years
在 date 之外,type 还支持周、月、年以及"多选"形态(dates、months、years),它们都复用同一面板体系,只是内部 selectionMode 不同:
<div class="container">
<div class="block">
<span class="demonstration">Week</span>
<el-date-picker
v-model="value1"
type="week"
format="Week WW"
placeholder="Pick a week">
</el-date-picker>
</div>
<div class="block">
<span class="demonstration">Month</span>
<el-date-picker
v-model="value2"
type="month"
placeholder="Pick a month">
</el-date-picker>
</div>
</div>
<div class="container">
<div class="block">
<span class="demonstration">Year</span>
<el-date-picker
v-model="value3"
type="year"
placeholder="Pick a year">
</el-date-picker>
</div>
<div class="block">
<span class="demonstration">Dates</span>
<el-date-picker
type="dates"
v-model="value4"
placeholder="Pick one or more dates">
</el-date-picker>
</div>
</div>
<div class="container">
<div class="block">
<span class="demonstration">months</span>
<el-date-picker
type="months"
v-model="value5"
placeholder="Pick one or more months">
</el-date-picker>
</div>
<div class="block">
<span class="demonstration">years</span>
<el-date-picker
type="years"
v-model="value6"
placeholder="Pick one or more years">
</el-date-picker>
</div>
</div>
<script>
export default {
data() {
return {
value1: '',
value2: '',
value3: '',
value4: '',
value5: '',
value6: ''
};
}
};
</script>
源码印证:type 与面板的映射。picker/date-picker.js 中的 getPanel 决定了每种 type 实际挂载哪个面板组件:
daterange/datetimerange→DateRangePanel(panel/date-range.vue)monthrange→MonthRangePanel(panel/month-range.vue)- 其余类型(
date、week、month、year、dates、months、years等)→DatePanel(panel/date.vue)
并且 watch: type 会在运行期切换 type 时执行 unmountPicker + getPanel + mountPicker 重新挂载面板。selectionMode 的计算位于 picker.vue,week/month/year/dates/months/years 各自映射到同名模式,默认落到 day。值得注意的细节:多选类(dates、months、years)输入框在 picker.vue 模板 中被强制 readonly(不可手输),且 displayValue 会把数组用 ', ' 拼接展示(picker.vue);week 类型的展示格式比较特殊——DEFAULT_FORMATS.week 为 'yyyywWW',TYPE_VALUE_RESOLVER_MAP.week.formatter 会先按普通日期格式化,再用 getWeekNumber 的计算结果替换 W/WW 占位(picker.vue、date-util.js)。
三、日期区间(daterange)与 unlink-panels
组件原生支持区间选择。区间模式下左右两个面板默认联动(翻月/翻年时一起切换);如果希望两个面板独立展示当前月,可以添加 unlink-panels 属性。range-separator 用于自定义两个输入框之间的分隔文案,start-placeholder / end-placeholder 分别控制起止输入框的占位符。
<template>
<div class="block">
<span class="demonstration">Default</span>
<el-date-picker
v-model="value1"
type="daterange"
range-separator="To"
start-placeholder="Start date"
end-placeholder="End date">
</el-date-picker>
</div>
<div class="block">
<span class="demonstration">With quick options</span>
<el-date-picker
v-model="value2"
type="daterange"
align="right"
unlink-panels
range-separator="To"
start-placeholder="Start date"
end-placeholder="End date"
:picker-options="pickerOptions">
</el-date-picker>
</div>
</template>
<script>
export default {
data() {
return {
pickerOptions: {
shortcuts: [{
text: 'Last week',
onClick(picker) {
const end = new Date();
const start = new Date();
start.setTime(start.getTime() - 3600 * 1000 * 24 * 7);
picker.$emit('pick', [start, end]);
}
}, {
text: 'Last month',
onClick(picker) {
const end = new Date();
const start = new Date();
start.setTime(start.getTime() - 3600 * 1000 * 24 * 30);
picker.$emit('pick', [start, end]);
}
}, {
text: 'Last 3 months',
onClick(picker) {
const end = new Date();
const start = new Date();
start.setTime(start.getTime() - 3600 * 1000 * 24 * 90);
picker.$emit('pick', [start, end]);
}
}]
},
value1: '',
value2: ''
};
}
};
</script>
区间快捷选项与普通快捷选项的唯一区别:$emit('pick', <a href="https://link.gitcode.com/i/ab7d6a7ad09dd2a4ce9e032bef145b6b" target="_blank">start, end]) 要传一个长度为 2 的数组。区间值的输入/输出由 RANGE_FORMATTER / RANGE_PARSER 处理([picker.vue),解析时会按 rangeSeparator 把用户手输的字符串切成两段分别 parseDate。unlink-panels 通过 mountPicker 中的 this.picker.unlinkPanels = this.unlinkPanels(picker.vue)注入面板,最终由 DateRangePanel 控制左右面板是否共用同一个"当前月"状态。align="right" 对应 Popper 的 bottom-end 放置方式,映射表 PLACEMENT_MAP 定义在 picker.vue。
区间 UI 的结构也可以从 picker.vue 模板 看出:ranged(即 type.indexOf('range') > -1,picker.vue)为真时,组件渲染的不是 el-input,而是一个带 range-separator 插槽的自定义双 input 容器——所以 range-separator 插槽(见第五节)只对区间类型有意义。
四、月份区间(monthrange)
type="monthrange" 用于选择月份区间,联动与 unlink-panels 的语义同上(此时联动的是"当前年")。
<template>
<div class="block">
<span class="demonstration">Default</span>
<el-date-picker
v-model="value1"
type="monthrange"
range-separator="To"
start-placeholder="Start month"
end-placeholder="End month">
</el-date-picker>
</div>
<div class="block">
<span class="demonstration">With quick options</span>
<el-date-picker
v-model="value2"
type="monthrange"
align="right"
unlink-panels
range-separator="To"
start-placeholder="Start month"
end-placeholder="End month"
:picker-options="pickerOptions">
</el-date-picker>
</div>
</template>
<script>
export default {
data() {
return {
pickerOptions: {
shortcuts: [{
text: 'This month',
onClick(picker) {
picker.$emit('pick', [new Date(), new Date()]);
}
}, {
text: 'This year',
onClick(picker) {
const end = new Date();
const start = new Date(new Date().getFullYear(), 0);
picker.$emit('pick', [start, end]);
}
}, {
text: 'Last 6 months',
onClick(picker) {
const end = new Date();
const start = new Date();
start.setMonth(start.getMonth() - 6);
picker.$emit('pick', [start, end]);
}
}]
},
value1: '',
value2: ''
};
}
};
</script>
从源码结构看,monthrange 的显示格式默认为 'yyyy-MM'(picker.vue DEFAULT_FORMATS),面板为 MonthRangePanel,其内部由两个 basic/month-table.vue 组成,disabledDate 在月粒度上的判定逻辑是"该月所有日期全部被禁用则该月禁用"(month-table.vue),年粒度同理(year-table.vue)。
五、default-value 指定初始面板日期
用户尚未选择时,面板默认展示"今天"所在的日历页。用 default-value 可以固定面板初始打开的日期,其值需要能被 new Date() 解析(如 "2010-10-01")。当 type 为 daterange 时,default-value 只决定左侧面板的日历。
<template>
<div class="block">
<span class="demonstration">date</span>
<el-date-picker
v-model="value1"
type="date"
placeholder="Pick a date"
default-value="2010-10-01">
</el-date-picker>
</div>
<div class="block">
<span class="demonstration">daterange</span>
<el-date-picker
v-model="value2"
type="daterange"
align="right"
start-placeholder="Start Date"
end-placeholder="End Date"
default-value="2010-10-01">
</el-date-picker>
</div>
</template>
<script>
export default {
data() {
return {
value1: '',
value2: ''
};
}
};
</script>
实现链路上,defaultValue 是 picker.vue 的 prop,mountPicker 时同步给面板(this.picker.defaultValue = this.defaultValue,picker.vue),面板内部再以 :default-value="defaultValue ? new Date(defaultValue) : null" 传给 date-table / year-table / month-table(panel/date.vue)。date-picker.spec.js 中的 default value 用例(含 daterange 场景)验证了这一行为。
六、format 与 value-format:显示格式和绑定值格式分离
format:控制输入框中显示的文本格式;value-format:控制v-model绑定的值的格式。
默认情况下组件接受并返回 Date 对象。若希望绑定字符串(或时间戳),需要显式指定 value-format。注意占位符区分大小写,以 UTC 2017-01-02 03:04:05 为例,完整的格式符表如下:
| 格式符 | 含义 | 备注 | 示例 |
|---|---|---|---|
yyyy |
年 | 2017 | |
M |
月 | 不接受 0 | 1 |
MM |
月 | 01 | |
W |
周 | 仅用于 type="week" 的 format;不接受 0 |
1 |
WW |
周 | 仅用于 type="week" 的 format |
01 |
d |
日 | 不接受 0 | 2 |
dd |
日 | 02 | |
H |
时(24 小时制) | 不接受 0 | 3 |
HH |
时(24 小时制) | 03 | |
h |
时(12 小时制) | 需搭配 A 或 a;不接受 0 |
3 |
hh |
时(12 小时制) | 需搭配 A 或 a |
03 |
m |
分 | 不接受 0 | 4 |
mm |
分 | 04 | |
s |
秒 | 不接受 0 | 5 |
ss |
秒 | 05 | |
A |
AM/PM | 仅用于 format,大写 |
AM |
a |
am/pm | 仅用于 format,小写 |
am |
timestamp |
JS 时间戳 | 仅用于 value-format;绑定值必须是 number |
1483326245000 |
[MM] |
转义 | 方括号内的字符原样输出(如 [A] [MM]) |
MM |
<template>
<div class="block">
<span class="demonstration">Emits Date object</span>
<div class="demonstration">Value: {{ value1 }}</div>
<el-date-picker
v-model="value1"
type="date"
placeholder="Pick a Date"
format="yyyy/MM/dd">
</el-date-picker>
</div>
<div class="block">
<span class="demonstration">Use value-format</span>
<div class="demonstration">Value: {{ value2 }}</div>
<el-date-picker
v-model="value2"
type="date"
placeholder="Pick a Date"
format="yyyy/MM/dd"
value-format="yyyy-MM-dd">
</el-date-picker>
</div>
<div class="block">
<span class="demonstration">Timestamp</span>
<div class="demonstration">Value: {{ value3 }}</div>
<el-date-picker
v-model="value3"
type="date"
placeholder="Pick a Date"
format="yyyy/MM/dd"
value-format="timestamp">
</el-date-picker>
</div>
</template>
<script>
export default {
data() {
return {
value1: '',
value2: '',
value3: ''
};
}
};
</script>
源码印证:解析链路。value 进入组件后会先经过计算属性 parsedValue(picker.vue):如果值本身就是 Date(或全为 Date 的数组)则原样使用;若设置了 valueFormat,则走 parseAsFormatAndType 按格式解析;否则按"常见误用"兜底,直接 new Date(val)。选值回写时走 formatToValue(picker.vue):只有 valueFormat 存在且值可格式化时才做 Date → 字符串/时间戳 转换,否则原样发出 Date。timestamp 是特殊分支:DATE_FORMATTER / DATE_PARSER 中对 format === 'timestamp' 直接做 value.getTime() / new Date(Number(text))(picker.vue),这也是表格中"timestamp 仅用于 value-format"的原因。真正的字符级解析/格式化由 src/utils/date.js(fecha 实现)完成,formatDate / parseDate 的封装见 date-util.js,国际化词表(周名、月名、am/pm)由 getI18nSettings 从 locale 取(date-util.js)。单测中 value-format 章节(date-picker.spec.js)覆盖了字符串绑定、timestamp 绑定等场景。
七、default-time:区间选择时的起止时间
在区间模式下,选中日期后默认起止时间都是 00:00:00。用 default-time 可以给起止日期分别指定时间:它是一个至多两个 HH:mm:ss 字符串的数组,第一项作用于开始日期,第二项作用于结束日期。
<template>
<div class="block">
<p>Component value: {{ value }}</p>
<el-date-picker
v-model="value"
type="daterange"
start-placeholder="Start date"
end-placeholder="End date"
:default-time="['00:00:00', '23:59:59']">
</el-date-picker>
</div>
</template>
<script>
export default {
data() {
return {
value: ''
};
}
};
</script>
这是报表类查询的典型配置:<a href="https://link.gitcode.com/i/00978d713871c76d36c918c864bd5f84" target="_blank">'00:00:00', '23:59:59'] 让"按天选择"实际覆盖整天的数据范围。实现上 defaultTime 是 [picker.vue 的 prop,mountPicker 时注入面板(this.picker.defaultTime = this.defaultTime,picker.vue),由 DateRangePanel 在 pick 前把对应时间写入起止 Date 对象。
八、完整 API 参考
Attributes 属性
| 属性 | 说明 | 类型 | 可选值 | 默认值 |
|---|---|---|---|---|
| value / v-model | 绑定值 | date(DatePicker) / array(DateRangePicker) | — | — |
| readonly | 是否只读 | boolean | — | false |
| disabled | 是否禁用 | boolean | — | false |
| size | 输入框尺寸 | string | large/small/mini | — |
| editable | 文本框是否可输入 | boolean | — | true |
| clearable | 是否显示清空按钮 | boolean | — | true |
| placeholder | 非区间模式下的占位文本 | string | — | — |
| start-placeholder | 区间模式开始日期占位 | string | — | — |
| end-placeholder | 区间模式结束日期占位 | string | — | — |
| type | picker 类型 | string | year/month/date/dates/months/years/datetime/week/datetimerange/daterange/monthrange | date |
| format | 输入框中的显示格式 | string | 见上文格式表 | yyyy-MM-dd |
| align | 对齐方式 | string | left/center/right | left |
| popper-class | 下拉框自定义类名 | string | — | — |
| picker-options | 附加选项,见下节 | object | — | {} |
| range-separator | 区间分隔符 | string | — | '-' |
| default-value | 日历初始显示日期 | Date | 任何可被 new Date() 接受的值 |
— |
| default-time | 区间模式下起止日期的时间 | string[] | 两个 HH:mm:ss 风格字符串的数组,第一个是开始日期时间,第二个是结束日期时间 |
— |
| value-format | 绑定值的格式;未指定时绑定值为 Date 对象 | string | 见上文格式表 | — |
| name | 同原生 input 的 name |
string | — | — |
| unlink-panels | 区间模式下解除两个面板的联动 | boolean | — | false |
| prefix-icon | 前缀图标自定义类 | string | — | el-icon-date |
| clear-icon | 清空图标自定义类 | string | — | el-icon-circle-close |
| append-to-body | 是否把选择面板挂到 body 上 | boolean | — | true |
其中 format 的默认值并非统一的 yyyy-MM-dd:DEFAULT_FORMATS(picker.vue)按类型分别为 month: 'yyyy-MM'、datetime: 'yyyy-MM-dd HH:mm:ss'、week: 'yyyywWW'、daterange/monthrange: 'yyyy-MM-dd' / 'yyyy-MM'、datetimerange: 'yyyy-MM-dd HH:mm:ss'、year/years: 'yyyy' 等——文档表格中的 yyyy-MM-dd 是针对默认 type="date" 的情形。editable=false 时输入框整体 readonly(picker.vue);prefixIcon 未指定时由 triggerClass 计算:type 含 time 用 el-icon-time,否则用 el-icon-date(picker.vue)。
Picker Options(picker-options)
| 属性 | 说明 | 类型 | 可选值 | 默认值 |
|---|---|---|---|---|
| shortcuts | 快捷选项对象数组,字段见下表 | object[] | — | — |
| disabledDate | 判断某日期是否禁用的函数,参数为该日期,返回 boolean | function | — | — |
| cellClassName | 自定义单元格类名 | Function(Date) | — | — |
| firstDayOfWeek | 一周的第一天 | Number | 1 ~ 7 | 7 |
| onPick | 区间选中日期变化时触发,仅 daterange 与 datetimerange 支持 |
Function({ maxDate, minDate }) | — | — |
firstDayOfWeek 的默认值 7(周日)可在 panel/date.vue 与 panel/date-range.vue 的 data 中确认,它被逐层传给 date-table 用于生成周表头与单元格偏移(date-table.vue)。仓库测试中也有对应的回归用例(date-picker.spec.js 的 picker-options:firstDayOfWeek)。
Shortcuts 快捷选项
| 属性 | 说明 | 类型 | 可选值 | 默认值 |
|---|---|---|---|---|
| text | 快捷选项标题 | string | — | — |
| onClick | 点击时触发的函数,参数为 picker 实例(vm);通过 vm.$emit('pick', ...) 修改选中值,如 vm.$emit('pick', new Date()) |
function | — | — |
Events 事件
| 名称 | 说明 | 参数 |
|---|---|---|
| change | 用户确认值时触发 | 绑定到组件的值 |
| blur | 输入框失去焦点 | 组件实例 |
| focus | 输入框获得焦点 | 组件实例 |
从源码看,change 的触发时机是面板关闭时调用 emitChange(picker.vue),且内部用 valueEquals 与打开面板前的 valueOnOpen 做比较,值真正变化才发出 change(picker.vue);同时会向 ElFormItem dispatch el.form.change,这也是 date-picker 能驱动表单校验的原因之一。
Methods 方法
| 方法 | 说明 | 参数 |
|---|---|---|
| focus | 聚焦输入框 | — |
focus() 的实现区分了单输入与区间两种形态:非区间直接聚焦 el-input,区间则走 handleFocus 打开面板(picker.vue)。
Slots 插槽
| 名称 | 说明 |
|---|---|
| range-separator | 自定义区间分隔符 |
对应 picker.vue 模板 中的 <slot name="range-separator">,默认渲染为 <span class="el-range-separator">{{ rangeSeparator }}</span>。
九、行为细节与调试建议
结合源码,有几点行为值得在实际排错时留意:
- 键盘交互:
ESC关闭面板;Tab触发handleChange并关闭;Enter在手输内容合法时确认选择(picker.vue handleKeydown)。 - 手输值的合法性:手输回车后会调用面板的
isValidValue校验,非法输入不会写回v-model(picker.vue)。 - 多选类类型关闭即回滚:
dates/years/months在没有"确认"按钮的交互下,handleClose会把值恢复到打开面板前的valueOnOpen,避免点空白处误确认(picker.vue)。 - 面板是懒挂载的:
mountPicker发生在第一次打开面板时,用new Vue(this.panel).$mount()实例化面板并appendChild到组件元素内(picker.vue),所以pickerOptions的 deep watch、pick/select-range事件绑定都发生在这个时机。 selectableRange的隐藏能力:虽然文档表格未列出,源码支持pickerOptions.selectableRange,会被解析为datetimerange的时间范围数组并交给面板限制可选时段(picker.vue),测试覆盖见 date-picker.spec.js。
十、相关资源
- 组件入口与安装:packages/date-picker/index.js(
Vue.use后全局注册ElDatePicker) - 面板选择逻辑:picker/date-picker.js
- 通用 picker 封装(输入框 + Popper + 值解析):picker.vue
- 面板实现:panel/date.vue、panel/date-range.vue、panel/month-range.vue
- 基础表格组件:basic/date-table.vue、basic/month-table.vue、basic/year-table.vue、basic/time-spinner.vue
- 日期工具函数:src/utils/date-util.js
- 单元测试(覆盖输入事件、value-format、daterange、datetimerange、monthrange、firstDayOfWeek、selectableRange 等):test/unit/specs/date-picker.spec.js
- 中文文档同内容参考:examples/docs/zh-CN