DatePicker 日期选择器

用于选择或输入日期

TIP

在 SSR 场景下，您需要将组件包裹在 <client-only></client-only> 之中 (如: Nuxt) 和 SSG (e.g: VitePress).

选择某一天

以”日“为基本单位，基础的日期选择控件

其他日期单位

通过扩展基础的日期选择，可以选择周、月、年或多个日期

选择一段时间

你可以通过如下例子来学习如何设置一个日期范围选择器。

选择月份范围

你当然还可以选择一个月的范围。

默认值

日期选择器会在用户未选择任何日期的时候默认展示当天的日期。 你也可以使用 default-value 来修改这个默认的日期。 请注意该值需要是一个可以解析的 new Date() 对象。

如果类型是 daterange, default-value 则会设置左边窗口的默认值。

日期格式

使用format指定输入框的格式。 使用 value-format 指定绑定值的格式。

默认情况下，组件接受并返回Date对象。

在 这里 查看 Day.js 支持的所有格式。

WARNING

请一定要注意传入参数的大小写是否正确

默认显示日期

在选择日期范围时，你可以指定起始日期和结束日期的默认时间。

设置自定义前缀的内容

前缀内容可以被自定义。

自定义内容

弹出框的内容是可以自定义的，在插槽内你可以获取到当前单元格的数据

更详细的数据类型，请查看下表

interface DateCell {
  column: number
  customClass: string
  disabled: boolean
  end: boolean
  inRange: boolean
  row: number
  selected: Dayjs
  isCurrent: boolean
  isSelected: boolean
  start: boolean
  text: number
  timestamp: number
  date: Date
  dayjs: Dayjs
  type: 'normal' | 'today' | 'week' | 'next-month' | 'prev-month'
}

国际化

由于 Element Plus 的默认语言为英语，如果你需要设置其它的语言，请参考国际化文档。

要注意的是：日期相关的文字（月份，每一周的第一天等等）也都是通过国际化来配置的。

API

属性

属性名说明类型默认
model-value / v-model绑定值，如果它是数组，长度应该是 2number / string / object''
readonly只读booleanfalse
disabled禁用booleanfalse
size输入框尺寸enum—
editable文本框可输入booleantrue
clearable是否显示清除按钮booleantrue
placeholder非范围选择时的占位内容string''
start-placeholder范围选择时开始日期的占位内容string—
end-placeholder范围选择时结束日期的占位内容string—
type显示类型enumdate
format显示在输入框中的格式参见 date formatsYYYY-MM-DD
popper-classDatePicker 下拉框的类名string—
popper-options自定义 popper 选项，更多请参考 popper.jsobject{}
range-separator选择范围时的分隔符string'-'
default-value可选，选择器打开时默认显示的时间object—
default-time范围选择时选中日期所使用的当日内具体时刻object—
value-format可选，绑定值的格式。 不指定则绑定值为 Date 对象参见 date formats—
id等价于原生 input id 属性string / object—
name等价于原生 input name 属性string / object''
unlink-panels在范围选择器里取消两个日期面板之间的联动booleanfalse
prefix-icon自定义前缀图标 如果 type的值是TimeLikeType，那么就是 Clock，不然就是 Calendarstring / object''
clear-icon自定义清除图标string / objectCircleClose
validate-event是否触发表单验证booleantrue
disabled-date一个用来判断该日期是否被禁用的函数，接受一个 Date 对象作为参数。 应该返回一个 Boolean 值。Function—
shortcuts设置快捷选项，需要传入数组对象object[]
cell-class-name设置自定义类名Function—
teleported是否将 date-picker 的下拉列表插入至 body 元素booleantrue
empty-values 2.7.0组件的空值配置 参考config-providerarray—
value-on-clear 2.7.0清空选项的值 参考 config-providerstring / number / boolean / Function—

事件

事件名说明类型
change用户确认选定的值时触发Function
blur在组件 Input 失去焦点时触发Function
focus在组件 Input 获得焦点时触发Function
calendar-change在日历所选日期更改时触发Function
panel-change当日期面板改变时触发。Function
visible-change当 DatePicker 的下拉列表出现/消失时触发Function

插槽

名称说明
default自定义单元格内容
range-separator自定义范围分割符内容

暴露

插槽名说明类型
focus使选择器的输入框获取焦点Function
handleOpen 2.2.16打开日期选择器弹窗Function
handleClose 2.2.16关闭日期选择器弹窗Function

类型声明

显示类型声明
import type { Options as PopperOptions } from '@popperjs/core'

type TimeLikeType = 'datetime' | 'datetimerange'

源代码

组件 • 文档

贡献者