Element (Vue 2) Date Picker 完整指南:从 type 体系、格式控制到 Range 面板的源码级解析

原创2026-09-17 10:52:251,727 阅读
文章标签:前端UI组件设计系统国际化

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 实际挂载哪个面板组件:

并且 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>。

九、行为细节与调试建议

结合源码,有几点行为值得在实际排错时留意:

  1. 键盘交互:ESC 关闭面板;Tab 触发 handleChange 并关闭;Enter 在手输内容合法时确认选择(picker.vue handleKeydown)。
  2. 手输值的合法性:手输回车后会调用面板的 isValidValue 校验,非法输入不会写回 v-model(picker.vue)。
  3. 多选类类型关闭即回滚:dates/years/months 在没有"确认"按钮的交互下,handleClose 会把值恢复到打开面板前的 valueOnOpen,避免点空白处误确认(picker.vue)。
  4. 面板是懒挂载的:mountPicker 发生在第一次打开面板时,用 new Vue(this.panel).$mount() 实例化面板并 appendChild 到组件元素内(picker.vue),所以 pickerOptions 的 deep watch、pick/select-range 事件绑定都发生在这个时机。
  5. selectableRange 的隐藏能力:虽然文档表格未列出,源码支持 pickerOptions.selectableRange,会被解析为 datetimerange 的时间范围数组并交给面板限制可选时段(picker.vue),测试覆盖见 date-picker.spec.js。

十、相关资源

登录后查看全文
element