Date Picker 日期选择器

日期选择器用于选择或输入日期。VISTA B 直接使用 Element Plus 的 el-date-picker，样式沿用组件库，适合筛选时间、配置有效期、设置项目节点、选择统计周期等场景。

选择某一天

通过 type="date" 选择单个日期。shortcuts 可以配置快捷选项，disabled-date 可以禁用不可选日期。

vue

<script setup>
import { ref } from 'vue'

const value = ref('')
const shortcuts = [
  { text: '今天', value: new Date() },
  {
    text: '昨天',
    value: () => {
      const date = new Date()
      date.setDate(date.getDate() - 1)
      return date
    }
  }
]

const disabledDate = (time) => {
  return time.getTime() > Date.now()
}
</script>

<template>
  <el-date-picker
    v-model="value"
    type="date"
    placeholder="选择日期"
    :shortcuts="shortcuts"
    :disabled-date="disabledDate"
    value-format="YYYY-MM-DD"
  />
</template>

其他日期单位

通过 type 可以选择年、月、周或多个日期。当前 VISTA B 常用年、月、日；周和多日期适合统计周期或批量排期。

vue

<el-date-picker v-model="year" type="year" value-format="YYYY" />
<el-date-picker v-model="month" type="month" value-format="YYYY-MM" />
<el-date-picker v-model="week" type="week" format="YYYY 第 ww 周" />
<el-date-picker v-model="dates" type="dates" value-format="YYYY-MM-DD" />

日期范围

设置 type="daterange" 后可选择一段日期。范围选择器使用 start-placeholder、end-placeholder 和 range-separator 分别配置起止占位和分隔文本。

至

vue

<el-date-picker
  v-model="value"
  type="daterange"
  range-separator="至"
  start-placeholder="开始日期"
  end-placeholder="结束日期"
  value-format="YYYY-MM-DD"
/>

月份范围

设置 type="monthrange" 后可选择一段月份，适合统计周期、账期、项目阶段这类按月归档的数据。

至

vue

<el-date-picker
  v-model="value"
  type="monthrange"
  range-separator="至"
  start-placeholder="开始月份"
  end-placeholder="结束月份"
  value-format="YYYY-MM"
/>

年份范围

设置 type="yearrange" 后可选择一段年份，适合年度计划、年度报表、合同有效年度等场景。

至

vue

<el-date-picker
  v-model="value"
  type="yearrange"
  range-separator="至"
  start-placeholder="开始年份"
  end-placeholder="结束年份"
  value-format="YYYY"
/>

单个面板

范围选择器默认展示两个面板。设置 single-panel 后只展示一个面板，适合空间有限的筛选区或侧边栏。

至

vue

<el-date-picker
  v-model="value"
  type="daterange"
  single-panel
  range-separator="至"
  start-placeholder="开始日期"
  end-placeholder="结束日期"
/>

日期格式

format 控制输入框展示格式，value-format 控制绑定值格式。不设置 value-format 时，绑定值为 Date 对象。

vue

<el-date-picker
  v-model="value"
  type="date"
  format="YYYY/MM/DD"
  value-format="YYYY-MM-DD"
/>

默认显示日期

使用 default-value 可以控制面板打开时默认显示的日期。范围选择还可以通过 default-time 设置选中日期的默认时分秒。

至

vue

<script setup>
const defaultValue = new Date(2026, 4, 1)
const defaultTime = [
  new Date(2000, 1, 1, 0, 0, 0),
  new Date(2000, 1, 1, 23, 59, 59)
]
</script>

<template>
  <el-date-picker
    v-model="value"
    type="daterange"
    :default-value="defaultValue"
    :default-time="defaultTime"
    value-format="YYYY-MM-DD HH:mm:ss"
  />
</template>

自定义内容

通过默认插槽可以自定义日期单元格内容。插槽会提供当前单元格数据，可用于标记项目节点、节假日或特殊状态。

vue

<el-date-picker v-model="value" type="date">
  <template #default="{ text, dayjs }">
    <div>
      <span>{{ text }}</span>
      <span v-if="isMilestoneDate(dayjs)" class="date-dot" />
    </div>
  </template>
</el-date-picker>

自定义图标

使用 prefix-icon 和 clear-icon 可以替换输入框前缀图标和清除图标。也可以通过 prev-month、next-month、prev-year、next-year 插槽自定义面板切换图标。

vue

<script setup>
import { Calendar, CircleClose } from '@element-plus/icons-vue'
</script>

<template>
  <el-date-picker
    v-model="value"
    type="date"
    :prefix-icon="Calendar"
    :clear-icon="CircleClose"
    clearable
  />
</template>

API

DatePicker 属性

属性	说明	类型	默认值
`model-value` / `v-model`	绑定值；范围选择器应为长度为 2 的数组	`number` / `string` / `Date` / `array`	空
`readonly`	是否只读	`boolean`	`false`
`disabled`	是否禁用	`boolean`	`false`
`size`	输入框尺寸	`large` / `default` / `small`	空
`editable`	文本框是否可输入	`boolean`	`true`
`clearable`	是否显示清除按钮	`boolean`	`true`
`placeholder`	非范围选择时的占位内容	`string`	空
`start-placeholder`	范围选择时开始日期的占位内容	`string`	空
`end-placeholder`	范围选择时结束日期的占位内容	`string`	空
`type`	显示类型	`year` / `years` / `month` / `months` / `date` / `dates` / `week` / `datetime` / `daterange` / `monthrange` / `yearrange` / `datetimerange`	`date`
`format`	显示在输入框中的格式	`string`	`YYYY-MM-DD`
`value-format`	绑定值的格式；不设置时绑定值为 `Date` 对象	`string`	空
`popper-class`	下拉框自定义类名	`string`	空
`popper-style`	下拉框自定义样式	`string` / `object`	空
`popper-options`	自定义 Popper 配置	`object`	`{}`
`range-separator`	范围选择时的分隔符	`string`	`-`
`default-value`	面板打开时默认显示的日期	`Date` / `array`	空
`default-time`	范围选择时选中日期使用的默认时分秒	`Date` / `array`	空
`id`	原生 input `id` 属性	`string` / `array`	空
`name`	原生 input `name` 属性	`string` / `array`	空
`unlink-panels`	范围选择器中取消两个日期面板之间的联动	`boolean`	`false`
`single-panel`	范围选择器中只显示一个面板	`boolean`	`false`
`prefix-icon`	自定义前缀图标	`string` / `Component`	空
`clear-icon`	自定义清除图标	`string` / `Component`	`CircleClose`
`validate-event`	是否触发表单校验	`boolean`	`true`
`disabled-date`	判断日期是否禁用的函数	`(date: Date) => boolean`	空
`shortcuts`	快捷选项数组	`array`	`[]`
`cell-class-name`	自定义日期单元格类名	`(date: Date) => string`	空
`teleported`	下拉框是否挂载到 `body`	`boolean`	`true`
`empty-values`	组件空值配置	`array`	空
`value-on-clear`	点击清空后的值	`string` / `number` / `boolean` / `Function`	空
`fallback-placements`	下拉框可用的备用位置	`array`	`['bottom', 'top', 'right', 'left']`
`placement`	下拉框出现的位置	`Placement`	`bottom`
`show-footer`	是否显示底部区域	`boolean`	`true`
`show-confirm`	是否显示确定按钮	`boolean`	`true`
`show-week-number`	是否显示周数，周选择器除外	`boolean`	`false`
`automatic-dropdown`	输入框获得焦点时是否自动弹出面板	`boolean`	`true`

DatePicker 事件

事件名	说明	类型
`change`	用户确认值或点击外部后触发	`(value) => void`
`blur`	输入框失去焦点时触发	`(event: FocusEvent) => void`
`focus`	输入框获得焦点时触发	`(event: FocusEvent) => void`
`clear`	点击清除按钮时触发	`() => void`
`calendar-change`	范围选择器中日历所选日期变化时触发	`(value) => void`
`panel-change`	日期面板改变时触发	`(date, mode, view) => void`
`visible-change`	下拉框显示或隐藏时触发	`(visible: boolean) => void`

DatePicker 插槽

插槽	说明
`default`	自定义日期单元格内容
`range-separator`	自定义范围分隔符内容
`prev-month`	自定义上个月图标
`next-month`	自定义下个月图标
`prev-year`	自定义上一年图标
`next-year`	自定义下一年图标

DatePicker 暴露

方法名	说明	类型
`focus`	使组件获取焦点	`() => void`
`blur`	使组件失去焦点	`() => void`
`handleOpen`	打开日期选择器弹窗	`() => void`
`handleClose`	关闭日期选择器弹窗	`() => void`

Date Picker 日期选择器 ​

选择某一天 ​

其他日期单位 ​

日期范围 ​

月份范围 ​

年份范围 ​

单个面板 ​

日期格式 ​

默认显示日期 ​

自定义内容 ​

自定义图标 ​

API ​

DatePicker 属性 ​

DatePicker 事件 ​

DatePicker 插槽 ​

DatePicker 暴露 ​