DatePicker 日期选择器

用于选择或输入日期

选择某一天

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

基本单位由 type 属性指定。 通过 shortcuts 配置快捷选项, 禁用日期通过 disabledDate 设置,传入函数

Date Picker 日期选择器 - 图1

  1. <template>
  2. <div>
  3. <el-radio-group v-model="size" label="size control">
  4. <el-radio-button label="large">large</el-radio-button>
  5. <el-radio-button label="default">default</el-radio-button>
  6. <el-radio-button label="small">small</el-radio-button>
  7. </el-radio-group>
  8. </div>
  9. <div class="demo-date-picker">
  10. <div class="block">
  11. <span class="demonstration">Default</span>
  12. <el-date-picker
  13. v-model="value1"
  14. type="date"
  15. placeholder="Pick a day"
  16. :size="size"
  17. />
  18. </div>
  19. <div class="block">
  20. <span class="demonstration">Picker with quick options</span>
  21. <el-date-picker
  22. v-model="value2"
  23. type="date"
  24. placeholder="Pick a day"
  25. :disabled-date="disabledDate"
  26. :shortcuts="shortcuts"
  27. :size="size"
  28. />
  29. </div>
  30. </div>
  31. </template>
  32. <script lang="ts" setup>
  33. import { ref } from 'vue'
  34. const size = ref<'' | 'large' | 'small'>('')
  35. const value1 = ref('')
  36. const value2 = ref('')
  37. const shortcuts = [
  38. {
  39. text: 'Today',
  40. value: new Date(),
  41. },
  42. {
  43. text: 'Yesterday',
  44. value: () => {
  45. const date = new Date()
  46. date.setTime(date.getTime() - 3600 * 1000 * 24)
  47. return date
  48. },
  49. },
  50. {
  51. text: 'A week ago',
  52. value: () => {
  53. const date = new Date()
  54. date.setTime(date.getTime() - 3600 * 1000 * 24 * 7)
  55. return date
  56. },
  57. },
  58. ]
  59. const disabledDate = (time: Date) => {
  60. return time.getTime() > Date.now()
  61. }
  62. </script>
  63. <style scoped>
  64. .demo-date-picker {
  65. display: flex;
  66. width: 100%;
  67. padding: 0;
  68. flex-wrap: wrap;
  69. }
  70. .demo-date-picker .block {
  71. padding: 30px 0;
  72. text-align: center;
  73. border-right: solid 1px var(--el-border-color);
  74. flex: 1;
  75. }
  76. .demo-date-picker .block:last-child {
  77. border-right: none;
  78. }
  79. .demo-date-picker .demonstration {
  80. display: block;
  81. color: var(--el-text-color-secondary);
  82. font-size: 14px;
  83. margin-bottom: 20px;
  84. }
  85. </style>

其他日期单位

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

Date Picker 日期选择器 - 图2

  1. <template>
  2. <div class="demo-date-picker">
  3. <div class="container">
  4. <div class="block">
  5. <span class="demonstration">Week</span>
  6. <el-date-picker
  7. v-model="value1"
  8. type="week"
  9. format="[Week] ww"
  10. placeholder="Pick a week"
  11. />
  12. </div>
  13. <div class="block">
  14. <span class="demonstration">Month</span>
  15. <el-date-picker
  16. v-model="value2"
  17. type="month"
  18. placeholder="Pick a month"
  19. />
  20. </div>
  21. </div>
  22. <div class="container">
  23. <div class="block">
  24. <span class="demonstration">Year</span>
  25. <el-date-picker
  26. v-model="value3"
  27. type="year"
  28. placeholder="Pick a year"
  29. />
  30. </div>
  31. <div class="block">
  32. <span class="demonstration">Dates</span>
  33. <el-date-picker
  34. v-model="value4"
  35. type="dates"
  36. placeholder="Pick one or more dates"
  37. />
  38. </div>
  39. </div>
  40. </div>
  41. </template>
  42. <script lang="ts" setup>
  43. import { ref } from 'vue'
  44. const value1 = ref('')
  45. const value2 = ref('')
  46. const value3 = ref('')
  47. const value4 = ref('')
  48. </script>
  49. <style scoped>
  50. .demo-date-picker {
  51. display: flex;
  52. width: 100%;
  53. padding: 0;
  54. flex-wrap: wrap;
  55. }
  56. .demo-date-picker .block {
  57. padding: 30px 0;
  58. text-align: center;
  59. border-right: solid 1px var(--el-border-color);
  60. flex: 1;
  61. }
  62. .demo-date-picker .block:last-child {
  63. border-right: none;
  64. }
  65. .demo-date-picker .container {
  66. flex: 1;
  67. border-right: solid 1px var(--el-border-color);
  68. }
  69. .demo-date-picker .container .block {
  70. border-right: none;
  71. }
  72. .demo-date-picker .container .block:last-child {
  73. border-top: solid 1px var(--el-border-color);
  74. }
  75. .demo-date-picker .container:last-child {
  76. border-right: none;
  77. }
  78. .demo-date-picker .demonstration {
  79. display: block;
  80. color: var(--el-text-color-secondary);
  81. font-size: 14px;
  82. margin-bottom: 20px;
  83. }
  84. </style>

选择一段时间

可在一个选择器中便捷地选择一个时间范围

在选择日期范围时,默认情况下左右面板会联动。 如果希望两个面板各自独立切换当前月份,可以使用 unlink-panels 属性解除联动。

Date Picker 日期选择器 - 图3

  1. <template>
  2. <div>
  3. <el-radio-group v-model="size" label="size control">
  4. <el-radio-button label="large">large</el-radio-button>
  5. <el-radio-button label="default">default</el-radio-button>
  6. <el-radio-button label="small">small</el-radio-button>
  7. </el-radio-group>
  8. </div>
  9. <div class="demo-date-picker">
  10. <div class="block">
  11. <span class="demonstration">Default</span>
  12. <el-date-picker
  13. v-model="value1"
  14. type="daterange"
  15. range-separator="To"
  16. start-placeholder="Start date"
  17. end-placeholder="End date"
  18. :size="size"
  19. />
  20. </div>
  21. <div class="block">
  22. <span class="demonstration">With quick options</span>
  23. <el-date-picker
  24. v-model="value2"
  25. type="daterange"
  26. unlink-panels
  27. range-separator="To"
  28. start-placeholder="Start date"
  29. end-placeholder="End date"
  30. :shortcuts="shortcuts"
  31. :size="size"
  32. />
  33. </div>
  34. </div>
  35. </template>
  36. <script lang="ts" setup>
  37. import { ref } from 'vue'
  38. const size = ref<'' | 'large' | 'small'>('')
  39. const value1 = ref('')
  40. const value2 = ref('')
  41. const shortcuts = [
  42. {
  43. text: 'Last week',
  44. value: () => {
  45. const end = new Date()
  46. const start = new Date()
  47. start.setTime(start.getTime() - 3600 * 1000 * 24 * 7)
  48. return [start, end]
  49. },
  50. },
  51. {
  52. text: 'Last month',
  53. value: () => {
  54. const end = new Date()
  55. const start = new Date()
  56. start.setTime(start.getTime() - 3600 * 1000 * 24 * 30)
  57. return [start, end]
  58. },
  59. },
  60. {
  61. text: 'Last 3 months',
  62. value: () => {
  63. const end = new Date()
  64. const start = new Date()
  65. start.setTime(start.getTime() - 3600 * 1000 * 24 * 90)
  66. return [start, end]
  67. },
  68. },
  69. ]
  70. </script>
  71. <style scoped>
  72. .demo-date-picker {
  73. display: flex;
  74. width: 100%;
  75. padding: 0;
  76. flex-wrap: wrap;
  77. }
  78. .demo-date-picker .block {
  79. padding: 30px 0;
  80. text-align: center;
  81. border-right: solid 1px var(--el-border-color);
  82. flex: 1;
  83. }
  84. .demo-date-picker .block:last-child {
  85. border-right: none;
  86. }
  87. .demo-date-picker .demonstration {
  88. display: block;
  89. color: var(--el-text-color-secondary);
  90. font-size: 14px;
  91. margin-bottom: 20px;
  92. }
  93. </style>

选择月份范围

可在一个选择器中便捷地选择一个月份范围

在选择日期范围时,默认情况下左右面板会联动。 如果希望两个面板各自独立切换当前年份,可以使用 unlink-panels 属性解除联动。

Date Picker 日期选择器 - 图4

  1. <template>
  2. <div class="demo-date-picker">
  3. <div class="block">
  4. <span class="demonstration">Default</span>
  5. <el-date-picker
  6. v-model="value1"
  7. type="monthrange"
  8. range-separator="To"
  9. start-placeholder="Start month"
  10. end-placeholder="End month"
  11. />
  12. </div>
  13. <div class="block">
  14. <span class="demonstration">With quick options</span>
  15. <el-date-picker
  16. v-model="value2"
  17. type="monthrange"
  18. unlink-panels
  19. range-separator="To"
  20. start-placeholder="Start month"
  21. end-placeholder="End month"
  22. :shortcuts="shortcuts"
  23. />
  24. </div>
  25. </div>
  26. </template>
  27. <script lang="ts" setup>
  28. import { ref } from 'vue'
  29. const value1 = ref('')
  30. const value2 = ref('')
  31. const shortcuts = [
  32. {
  33. text: 'This month',
  34. value: [new Date(), new Date()],
  35. },
  36. {
  37. text: 'This year',
  38. value: () => {
  39. const end = new Date()
  40. const start = new Date(new Date().getFullYear(), 0)
  41. return [start, end]
  42. },
  43. },
  44. {
  45. text: 'Last 6 months',
  46. value: () => {
  47. const end = new Date()
  48. const start = new Date()
  49. start.setMonth(start.getMonth() - 6)
  50. return [start, end]
  51. },
  52. },
  53. ]
  54. </script>
  55. <style scoped>
  56. .demo-date-picker {
  57. display: flex;
  58. width: 100%;
  59. padding: 0;
  60. flex-wrap: wrap;
  61. }
  62. .demo-date-picker .block {
  63. padding: 30px 0;
  64. text-align: center;
  65. border-right: solid 1px var(--el-border-color);
  66. flex: 1;
  67. }
  68. .demo-date-picker .block:last-child {
  69. border-right: none;
  70. }
  71. .demo-date-picker .demonstration {
  72. display: block;
  73. color: var(--el-text-color-secondary);
  74. font-size: 14px;
  75. margin-bottom: 20px;
  76. }
  77. </style>

默认值

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

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

Date Picker 日期选择器 - 图5

  1. <template>
  2. <div class="demo-date-picker">
  3. <div class="block">
  4. <span class="demonstration">date</span>
  5. <el-date-picker
  6. v-model="value1"
  7. type="date"
  8. placeholder="Pick a date"
  9. :default-value="new Date(2010, 9, 1)"
  10. />
  11. </div>
  12. <div class="block">
  13. <span class="demonstration">daterange</span>
  14. <el-date-picker
  15. v-model="value2"
  16. type="daterange"
  17. start-placeholder="Start Date"
  18. end-placeholder="End Date"
  19. :default-value="[new Date(2010, 9, 1), new Date(2010, 10, 1)]"
  20. />
  21. </div>
  22. </div>
  23. </template>
  24. <script lang="ts" setup>
  25. import { ref } from 'vue'
  26. const value1 = ref('')
  27. const value2 = ref('')
  28. </script>
  29. <style scoped>
  30. .demo-date-picker {
  31. display: flex;
  32. width: 100%;
  33. padding: 0;
  34. flex-wrap: wrap;
  35. }
  36. .demo-date-picker .block {
  37. padding: 30px 0;
  38. text-align: center;
  39. border-right: solid 1px var(--el-border-color);
  40. flex: 1;
  41. }
  42. .demo-date-picker .block:last-child {
  43. border-right: none;
  44. }
  45. .demo-date-picker .demonstration {
  46. display: block;
  47. color: var(--el-text-color-secondary);
  48. font-size: 14px;
  49. margin-bottom: 20px;
  50. }
  51. </style>

日期格式

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

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

这里 Date Picker 日期选择器 - 图6 查看 Day.js 支持的 format 参数。

WARNING

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

Date Picker 日期选择器 - 图7

  1. <template>
  2. <div class="demo-date-picker">
  3. <div class="block">
  4. <span class="demonstration">Emits Date object</span>
  5. <div class="demonstration">Value: {{ value1 }}</div>
  6. <el-date-picker
  7. v-model="value1"
  8. type="date"
  9. placeholder="Pick a Date"
  10. format="YYYY/MM/DD"
  11. />
  12. </div>
  13. <div class="block">
  14. <span class="demonstration">Use value-format</span>
  15. <div class="demonstration">Value:{{ value2 }}</div>
  16. <el-date-picker
  17. v-model="value2"
  18. type="date"
  19. placeholder="Pick a Date"
  20. format="YYYY/MM/DD"
  21. value-format="YYYY-MM-DD"
  22. />
  23. </div>
  24. <div class="block">
  25. <span class="demonstration">Timestamp</span>
  26. <div class="demonstration">Value:{{ value3 }}</div>
  27. <el-date-picker
  28. v-model="value3"
  29. type="date"
  30. placeholder="Pick a Date"
  31. format="YYYY/MM/DD"
  32. value-format="x"
  33. />
  34. </div>
  35. </div>
  36. </template>
  37. <script lang="ts" setup>
  38. import { ref } from 'vue'
  39. const value1 = ref('')
  40. const value2 = ref('')
  41. const value3 = ref('')
  42. </script>
  43. <style scoped>
  44. .demo-date-picker {
  45. display: flex;
  46. width: 100%;
  47. padding: 0;
  48. flex-wrap: wrap;
  49. }
  50. .demo-date-picker .block {
  51. padding: 30px 0;
  52. text-align: center;
  53. border-right: solid 1px var(--el-border-color);
  54. flex: 1;
  55. }
  56. .demo-date-picker .block:last-child {
  57. border-right: none;
  58. }
  59. .demo-date-picker .demonstration {
  60. display: block;
  61. color: var(--el-text-color-secondary);
  62. font-size: 14px;
  63. margin-bottom: 20px;
  64. }
  65. </style>

默认显示日期

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

默认情况下,开始日期和结束日期的时间部分都是选择日期当日的 00:00:00。 通过 default-time 可以分别指定开始日期和结束日期的具体时刻。 它接受最多两个日期对象的数组。 其中第一项控制起始日期的具体时刻,第二项控制结束日期的具体时刻。

Date Picker 日期选择器 - 图8

  1. <template>
  2. <div class="demo-date-picker">
  3. <div class="block">
  4. <p>Component value:{{ value }}</p>
  5. <el-date-picker
  6. v-model="value"
  7. type="daterange"
  8. start-placeholder="Start date"
  9. end-placeholder="End date"
  10. :default-time="defaultTime"
  11. />
  12. </div>
  13. </div>
  14. </template>
  15. <script lang="ts" setup>
  16. import { ref } from 'vue'
  17. const value = ref('')
  18. const defaultTime = ref([
  19. new Date(2000, 1, 1, 0, 0, 0),
  20. new Date(2000, 2, 1, 23, 59, 59),
  21. ])
  22. </script>
  23. <style scoped>
  24. .demo-date-picker {
  25. display: flex;
  26. width: 100%;
  27. padding: 0;
  28. flex-wrap: wrap;
  29. }
  30. .demo-date-picker .block {
  31. padding: 30px 0;
  32. text-align: center;
  33. border-right: solid 1px var(--el-border-color);
  34. flex: 1;
  35. }
  36. .demo-date-picker .block:last-child {
  37. border-right: none;
  38. }
  39. </style>

设置自定义前缀的内容

前缀内容可以被自定义。

当你从其他vue组件或由渲染函数生成的组件中导入组件时, 你可以设置 prefix-icon 属性来定制前缀内容

Date Picker 日期选择器 - 图9

  1. <template>
  2. <div class="demo-date-picker">
  3. <div class="block">
  4. <span class="demonstration">set prefix-icon</span>
  5. <el-date-picker
  6. v-model="value1"
  7. type="date"
  8. placeholder="Pick a day"
  9. :prefix-icon="customPrefix"
  10. />
  11. </div>
  12. </div>
  13. </template>
  14. <script lang="ts" setup>
  15. import { h, ref, shallowRef } from 'vue'
  16. const value1 = ref('')
  17. const customPrefix = shallowRef({
  18. render() {
  19. return h('p', 'pre')
  20. },
  21. })
  22. </script>
  23. <style scoped>
  24. .demo-date-picker {
  25. display: flex;
  26. width: 100%;
  27. padding: 0;
  28. flex-wrap: wrap;
  29. }
  30. .demo-date-picker .block {
  31. padding: 30px 0;
  32. text-align: center;
  33. border-right: solid 1px var(--el-border-color);
  34. flex: 1;
  35. }
  36. .demo-date-picker .block:last-child {
  37. border-right: none;
  38. }
  39. .demo-date-picker .demonstration {
  40. display: block;
  41. color: var(--el-text-color-secondary);
  42. font-size: 14px;
  43. margin-bottom: 20px;
  44. }
  45. </style>

自定义内容

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

Date Picker 日期选择器 - 图10

  1. <template>
  2. <div class="demo-date-picker">
  3. <el-date-picker
  4. v-model="value"
  5. type="date"
  6. placeholder="Pick a day"
  7. format="YYYY/MM/DD"
  8. value-format="YYYY-MM-DD"
  9. >
  10. <template #default="cell">
  11. <div class="cell" :class="{ current: cell.isCurrent }">
  12. <span class="text">{{ cell.text }}</span>
  13. <span v-if="isHoliday(cell)" class="holiday" />
  14. </div>
  15. </template>
  16. </el-date-picker>
  17. </div>
  18. </template>
  19. <script lang="ts" setup>
  20. import { ref } from 'vue'
  21. const value = ref('2021-10-29')
  22. const holidays = [
  23. '2021-10-01',
  24. '2021-10-02',
  25. '2021-10-03',
  26. '2021-10-04',
  27. '2021-10-05',
  28. '2021-10-06',
  29. '2021-10-07',
  30. ]
  31. const isHoliday = ({ dayjs }) => {
  32. return holidays.includes(dayjs.format('YYYY-MM-DD'))
  33. }
  34. </script>
  35. <style scoped>
  36. .cell {
  37. height: 30px;
  38. padding: 3px 0;
  39. box-sizing: border-box;
  40. }
  41. .cell .text {
  42. width: 24px;
  43. height: 24px;
  44. display: block;
  45. margin: 0 auto;
  46. line-height: 24px;
  47. position: absolute;
  48. left: 50%;
  49. transform: translateX(-50%);
  50. border-radius: 50%;
  51. }
  52. .cell.current .text {
  53. background: #626aef;
  54. color: #fff;
  55. }
  56. .cell .holiday {
  57. position: absolute;
  58. width: 6px;
  59. height: 6px;
  60. background: var(--el-color-danger);
  61. border-radius: 50%;
  62. bottom: 0px;
  63. left: 50%;
  64. transform: translateX(-50%);
  65. }
  66. </style>

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

  1. interface DateCell {
  2. column: number
  3. customClass: string
  4. disabled: boolean
  5. end: boolean
  6. inRange: boolean
  7. row: number
  8. selected: Dayjs
  9. isCurrent: boolean
  10. isSelected: boolean
  11. start: boolean
  12. text: number
  13. timestamp: number
  14. date: Date
  15. dayjs: Dayjs
  16. type: 'normal' | 'today' | 'week' | 'next-month' | 'prev-month'
  17. }

国际化

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

要注意的是:日期相关的文字(月份,每一周的第一天等等)也都是通过国际化来配置的。

属性

属性说明类型可选值默认值
model-value / v-model选中项绑定值date(DatePicker) / array(DateRangePicker)
readonly只读booleanfalse
disabled禁用booleanfalse
size输入框尺寸stringlarge/default/smalldefault
editable文本框可输入booleantrue
clearable是否显示清除按钮booleantrue
placeholder非范围选择时的占位内容string
start-placeholder范围选择时开始日期的占位内容string
end-placeholder范围选择时结束日期的占位内容string
type显示类型stringyear/month/date/dates/datetime/ week/datetimerange/daterange/ monthrangedate
format显示在输入框中的格式string请查看 date formatsYYYY-MM-DD
popper-classDatePicker 下拉框的类名string
range-separator选择范围时的分隔符string‘-‘
default-value可选,选择器打开时默认显示的时间Dateanything accepted by new Date()
default-time范围选择时选中日期所使用的当日内具体时刻Date[]长度为2的数组,每一项都是Date对象。 第一项是起始日期,第二项是终止日期
value-format可选,绑定值的格式。 不指定则绑定值为 Date 对象string请查阅 date formats
id等价于原生 id 属性string / array(string)字符串 id=”my-date” 对应单个日期或数组 :id=”[‘my-range-start’, ‘my-range-end’]” 对应日期范围-
name等价于原生 name 属性string
unlink-panels在范围选择器里取消两个日期面板之间的联动booleanfalse
prefix-icon自定义前缀图标string | ComponentDate
clear-icon自定义清除图标string | ComponentCircleClose
validate-event输入时是否触发表单的校验boolean-true
disabled-date一个用来判断该日期是否被禁用的函数,接受一个 Date 对象作为参数。 应该返回一个 Boolean 值。function
shortcuts设置快捷选项,需要传入数组对象object[{ text: string, value: date / function }]
cell-class-name设置自定义类名Function(Date)
teleported是否将 date-picker 的下拉列表插入至 body 元素booleantrue / falsetrue

事件

事件名说明回调参数
change用户确认选定的值时触发(val: typeof v-model)
blur在组件 Input 失去焦点时触发(e: FocusEvent)
focus在组件 Input 获得焦点时触发(e: FocusEvent)
calendar-change如果用户没有选择日期,那默认展示当前日的月份。 你可以使用 default-value 来设置成其他的日期。(val: [Date, Date])
panel-change当日期面板改变时触发。(date, mode, view)
visible-change当 DatePicker 的下拉列表出现/消失时触发(visibility: boolean)

方法

方法名说明参数
focus使 input 获取焦点
handleOpen打开日期选择器弹窗
handleClose关闭日期选择器弹窗

插槽

插槽名说明
default自定义内容
range-separator自定义范围分割符内容

源代码

组件 Date Picker 日期选择器 - 图11 文档 Date Picker 日期选择器 - 图12

贡献者

Date Picker 日期选择器 - 图13 Jeremy

Date Picker 日期选择器 - 图14 三咲智子

Date Picker 日期选择器 - 图15 云游君

Date Picker 日期选择器 - 图16 msidolphin

Date Picker 日期选择器 - 图17 C.Y.Kun

Date Picker 日期选择器 - 图18 zz

Date Picker 日期选择器 - 图19 Alan Wang

Date Picker 日期选择器 - 图20 Aex

Date Picker 日期选择器 - 图21 LIUCHAO

Date Picker 日期选择器 - 图22 btea

Date Picker 日期选择器 - 图23 gjfei

Date Picker 日期选择器 - 图24 opengraphica

Date Picker 日期选择器 - 图25 Delyan Haralanov

Date Picker 日期选择器 - 图26 João Gonçalves

Date Picker 日期选择器 - 图27 wangzi

Date Picker 日期选择器 - 图28 qiang

Date Picker 日期选择器 - 图29 Xc

Date Picker 日期选择器 - 图30 Giwayume

Date Picker 日期选择器 - 图31 banbri

Date Picker 日期选择器 - 图32 iamkun

Date Picker 日期选择器 - 图33 Zivvvv

Date Picker 日期选择器 - 图34 lily-elephant

Date Picker 日期选择器 - 图35 Zhongxiang Wang

Date Picker 日期选择器 - 图36 0song

Date Picker 日期选择器 - 图37 Carter Li

Date Picker 日期选择器 - 图38 renovate[bot]

Date Picker 日期选择器 - 图39 内小子

Date Picker 日期选择器 - 图40 Hades-li

Date Picker 日期选择器 - 图41 weidehai