DatePicker 日期选择框

输入或选择日期的控件。

何时使用

当用户需要输入一个日期,可以点击标准输入框,弹出日期面板进行选择。

代码演示

DatePicker日期选择框 - 图1

基本

最简单的用法,在浮层中可以选择或者输入日期。

  1. <template>
  2. <div>
  3. <a-date-picker @change="onChange" />
  4. <br />
  5. <a-month-picker placeholder="Select month" @change="onChange" />
  6. <br />
  7. <a-range-picker @change="onChange" />
  8. <br />
  9. <a-week-picker placeholder="Select week" @change="onChange" />
  10. </div>
  11. </template>
  12. <script>
  13. export default {
  14. methods: {
  15. onChange(date, dateString) {
  16. console.log(date, dateString);
  17. },
  18. },
  19. };
  20. </script>

DatePicker日期选择框 - 图2

不可选择日期和时间

可用 disabledDatedisabledTime 分别禁止选择部分日期和时间,其中 disabledTime 需要和 showTime 一起使用。

  1. <template>
  2. <div>
  3. <a-date-picker
  4. format="YYYY-MM-DD HH:mm:ss"
  5. :disabled-date="disabledDate"
  6. :disabled-time="disabledDateTime"
  7. :show-time="{ defaultValue: moment('00:00:00', 'HH:mm:ss') }"
  8. />
  9. <br />
  10. <a-month-picker :disabled-date="disabledDate" placeholder="Select month" />
  11. <br />
  12. <a-range-picker
  13. :disabled-date="disabledDate"
  14. :disabled-time="disabledRangeTime"
  15. :show-time="{
  16. hideDisabledOptions: true,
  17. defaultValue: [moment('00:00:00', 'HH:mm:ss'), moment('11:59:59', 'HH:mm:ss')],
  18. }"
  19. format="YYYY-MM-DD HH:mm:ss"
  20. />
  21. </div>
  22. </template>
  23. <script>
  24. import moment from 'moment';
  25. export default {
  26. methods: {
  27. moment,
  28. range(start, end) {
  29. const result = [];
  30. for (let i = start; i < end; i++) {
  31. result.push(i);
  32. }
  33. return result;
  34. },
  35. disabledDate(current) {
  36. // Can not select days before today and today
  37. return current && current < moment().endOf('day');
  38. },
  39. disabledDateTime() {
  40. return {
  41. disabledHours: () => this.range(0, 24).splice(4, 20),
  42. disabledMinutes: () => this.range(30, 60),
  43. disabledSeconds: () => [55, 56],
  44. };
  45. },
  46. disabledRangeTime(_, type) {
  47. if (type === 'start') {
  48. return {
  49. disabledHours: () => this.range(0, 60).splice(4, 20),
  50. disabledMinutes: () => this.range(30, 60),
  51. disabledSeconds: () => [55, 56],
  52. };
  53. }
  54. return {
  55. disabledHours: () => this.range(0, 60).splice(20, 4),
  56. disabledMinutes: () => this.range(0, 31),
  57. disabledSeconds: () => [55, 56],
  58. };
  59. },
  60. },
  61. };
  62. </script>

DatePicker日期选择框 - 图3

额外的页脚

在浮层中加入额外的页脚,以满足某些定制信息的需求。

  1. <template>
  2. <div>
  3. <a-date-picker>
  4. <template slot="renderExtraFooter">
  5. extra footer
  6. </template>
  7. </a-date-picker>
  8. <a-date-picker show-time>
  9. <template slot="renderExtraFooter">
  10. extra footer
  11. </template>
  12. </a-date-picker>
  13. <a-range-picker>
  14. <template slot="renderExtraFooter">
  15. extra footer
  16. </template>
  17. </a-range-picker>
  18. <a-range-picker show-time>
  19. <template slot="renderExtraFooter">
  20. extra footer
  21. </template>
  22. </a-range-picker>
  23. <a-month-picker placeholder="Select month">
  24. <template slot="renderExtraFooter">
  25. extra footer
  26. </template>
  27. </a-month-picker>
  28. </div>
  29. </template>

DatePicker日期选择框 - 图4

受控面板

通过组合 modeonPanelChange 控制要展示的面板。

  1. <template>
  2. <div>
  3. <a-date-picker
  4. :mode="mode1"
  5. show-time
  6. @openChange="handleOpenChange1"
  7. @panelChange="handlePanelChange1"
  8. />
  9. <br />
  10. <a-range-picker
  11. :placeholder="['Start month', 'End month']"
  12. format="YYYY-MM"
  13. :value="value"
  14. :mode="mode2"
  15. @panelChange="handlePanelChange2"
  16. @change="handleChange"
  17. />
  18. </div>
  19. </template>
  20. <script>
  21. export default {
  22. data() {
  23. return {
  24. mode1: 'time',
  25. mode2: ['month', 'month'],
  26. value: [],
  27. };
  28. },
  29. methods: {
  30. handleOpenChange1(open) {
  31. if (open) {
  32. this.mode1 = 'time';
  33. }
  34. },
  35. handleChange(value) {
  36. this.value = value;
  37. },
  38. handlePanelChange1(value, mode) {
  39. this.mode1 = mode;
  40. },
  41. handlePanelChange2(value, mode) {
  42. this.value = value;
  43. this.mode2 = [mode[0] === 'date' ? 'month' : mode[0], mode[1] === 'date' ? 'month' : mode[1]];
  44. },
  45. },
  46. };
  47. </script>

DatePicker日期选择框 - 图5

三种大小

三种大小的输入框,若不设置,则为 default

  1. <template>
  2. <div>
  3. <a-radio-group v-model="size">
  4. <a-radio-button value="large">
  5. Large
  6. </a-radio-button>
  7. <a-radio-button value="default">
  8. Default
  9. </a-radio-button>
  10. <a-radio-button value="small">
  11. Small
  12. </a-radio-button>
  13. </a-radio-group>
  14. <br /><br />
  15. <a-date-picker :size="size" />
  16. <br />
  17. <a-month-picker :size="size" placeholder="Select Month" />
  18. <br />
  19. <a-range-picker :size="size" />
  20. <br />
  21. <a-week-picker :size="size" placeholder="Select Week" />
  22. </div>
  23. </template>
  24. <script>
  25. import moment from 'moment';
  26. export default {
  27. data() {
  28. return {
  29. size: 'default',
  30. };
  31. },
  32. };
  33. </script>

DatePicker日期选择框 - 图6

日期时间选择

增加选择时间功能,当 showTime 为一个对象时,其属性会传递给内建的 TimePicker

  1. <template>
  2. <div>
  3. <a-date-picker show-time placeholder="Select Time" @change="onChange" @ok="onOk" />
  4. <br />
  5. <a-range-picker
  6. :show-time="{ format: 'HH:mm' }"
  7. format="YYYY-MM-DD HH:mm"
  8. :placeholder="['Start Time', 'End Time']"
  9. @change="onChange"
  10. @ok="onOk"
  11. />
  12. </div>
  13. </template>
  14. <script>
  15. export default {
  16. methods: {
  17. onChange(value, dateString) {
  18. console.log('Selected Time: ', value);
  19. console.log('Formatted Selected Time: ', dateString);
  20. },
  21. onOk(value) {
  22. console.log('onOk: ', value);
  23. },
  24. },
  25. };
  26. </script>

DatePicker日期选择框 - 图7

后缀图标

最简单的用法,在浮层中可以选择或者输入日期。

  1. <template>
  2. <div>
  3. <a-date-picker @change="onChange">
  4. <a-icon slot="suffixIcon" type="smile" />
  5. </a-date-picker>
  6. <br />
  7. <a-month-picker placeholder="Select month" @change="onChange">
  8. <a-icon slot="suffixIcon" type="smile" />
  9. </a-month-picker>
  10. <br />
  11. <a-range-picker @change="onChange">
  12. <a-icon slot="suffixIcon" type="smile" />
  13. </a-range-picker>
  14. <br />
  15. <a-week-picker placeholder="Select week" @change="onChange">
  16. <a-icon slot="suffixIcon" type="smile" />
  17. </a-week-picker>
  18. <br />
  19. <a-date-picker suffix-icon="ab" @change="onChange" />
  20. <br />
  21. <a-month-picker suffix-icon="ab" placeholder="Select month" @change="onChange" />
  22. <br />
  23. <a-range-picker suffix-icon="ab" @change="onChange" />
  24. <br />
  25. <a-week-picker suffix-icon="ab" placeholder="Select week" @change="onChange" />
  26. </div>
  27. </template>
  28. <script>
  29. export default {
  30. methods: {
  31. onChange(date, dateString) {
  32. console.log(date, dateString);
  33. },
  34. },
  35. };
  36. </script>

DatePicker日期选择框 - 图8

定制日期单元格

使用 dateRender 可以自定义日期单元格的内容和样式。

  1. <template>
  2. <div>
  3. <a-date-picker>
  4. <template slot="dateRender" slot-scope="current, today">
  5. <div class="ant-calendar-date" :style="getCurrentStyle(current, today)">
  6. {{ current.date() }}
  7. </div>
  8. </template>
  9. </a-date-picker>
  10. <a-range-picker>
  11. <template slot="dateRender" slot-scope="current">
  12. <div class="ant-calendar-date" :style="getCurrentStyle(current)">
  13. {{ current.date() }}
  14. </div>
  15. </template>
  16. </a-range-picker>
  17. <a-week-picker>
  18. <template slot="dateRender" slot-scope="current">
  19. <div class="ant-calendar-date" :style="getCurrentStyle(current)">
  20. {{ current.date() }}
  21. </div>
  22. </template>
  23. </a-week-picker>
  24. </div>
  25. </template>
  26. <script>
  27. export default {
  28. methods: {
  29. getCurrentStyle(current, today) {
  30. const style = {};
  31. if (current.date() === 1) {
  32. style.border = '1px solid #1890ff';
  33. style.borderRadius = '50%';
  34. }
  35. return style;
  36. },
  37. },
  38. };
  39. </script>

DatePicker日期选择框 - 图9

禁用

选择框的不可用状态。

  1. <template>
  2. <div>
  3. <a-date-picker :default-value="moment('2015-06-06', dateFormat)" disabled />
  4. <br />
  5. <a-month-picker :default-value="moment('2015-06', 'YYYY-MM')" disabled />
  6. <br />
  7. <a-range-picker
  8. :default-value="[moment('2015-06-06', dateFormat), moment('2015-06-06', dateFormat)]"
  9. disabled
  10. />
  11. </div>
  12. </template>
  13. <script>
  14. import moment from 'moment';
  15. export default {
  16. data() {
  17. this.dateFormat = 'YYYY-MM-DD';
  18. return {};
  19. },
  20. methods: {
  21. moment,
  22. },
  23. };
  24. </script>

DatePicker日期选择框 - 图10

日期格式

使用 format 属性,可以自定义日期显示格式。

  1. <template>
  2. <div>
  3. <a-date-picker :default-value="moment('2015/01/01', dateFormat)" :format="dateFormat" />
  4. <br />
  5. <a-date-picker
  6. :default-value="moment('01/01/2015', dateFormatList[0])"
  7. :format="dateFormatList"
  8. />
  9. <br />
  10. <a-month-picker :default-value="moment('2015/01', monthFormat)" :format="monthFormat" />
  11. <br />
  12. <a-range-picker
  13. :default-value="[moment('2015/01/01', dateFormat), moment('2015/01/01', dateFormat)]"
  14. :format="dateFormat"
  15. />
  16. </div>
  17. </template>
  18. <script>
  19. import moment from 'moment';
  20. export default {
  21. data() {
  22. return {
  23. dateFormat: 'YYYY/MM/DD',
  24. monthFormat: 'YYYY/MM',
  25. dateFormatList: ['DD/MM/YYYY', 'DD/MM/YY'],
  26. };
  27. },
  28. methods: {
  29. moment,
  30. },
  31. };
  32. </script>

DatePicker日期选择框 - 图11

预设范围

可以预设常用的日期范围以提高用户体验。

  1. <template>
  2. <div>
  3. <a-range-picker
  4. :ranges="{ Today: [moment(), moment()], 'This Month': [moment(), moment().endOf('month')] }"
  5. @change="onChange"
  6. />
  7. <br />
  8. <a-range-picker
  9. :ranges="{ Today: [moment(), moment()], 'This Month': [moment(), moment().endOf('month')] }"
  10. show-time
  11. format="YYYY/MM/DD HH:mm:ss"
  12. @change="onChange"
  13. />
  14. </div>
  15. </template>
  16. <script>
  17. import moment from 'moment';
  18. export default {
  19. data() {
  20. return {
  21. dateFormat: 'YYYY/MM/DD',
  22. monthFormat: 'YYYY/MM',
  23. };
  24. },
  25. methods: {
  26. moment,
  27. onChange(dates, dateStrings) {
  28. console.log('From: ', dates[0], ', to: ', dates[1]);
  29. console.log('From: ', dateStrings[0], ', to: ', dateStrings[1]);
  30. },
  31. },
  32. };
  33. </script>

DatePicker日期选择框 - 图12

自定义日期范围选择

RangePicker 无法满足业务需求时,可以使用两个 DatePicker 实现类似的功能。

  • 通过设置 disabledDate 方法,来约束开始和结束日期。
  • 通过 open openChange 来优化交互。
  1. <template>
  2. <div>
  3. <a-date-picker
  4. v-model="startValue"
  5. :disabled-date="disabledStartDate"
  6. show-time
  7. format="YYYY-MM-DD HH:mm:ss"
  8. placeholder="Start"
  9. @openChange="handleStartOpenChange"
  10. />
  11. <a-date-picker
  12. v-model="endValue"
  13. :disabled-date="disabledEndDate"
  14. show-time
  15. format="YYYY-MM-DD HH:mm:ss"
  16. placeholder="End"
  17. :open="endOpen"
  18. @openChange="handleEndOpenChange"
  19. />
  20. </div>
  21. </template>
  22. <script>
  23. export default {
  24. data() {
  25. return {
  26. startValue: null,
  27. endValue: null,
  28. endOpen: false,
  29. };
  30. },
  31. watch: {
  32. startValue(val) {
  33. console.log('startValue', val);
  34. },
  35. endValue(val) {
  36. console.log('endValue', val);
  37. },
  38. },
  39. methods: {
  40. disabledStartDate(startValue) {
  41. const endValue = this.endValue;
  42. if (!startValue || !endValue) {
  43. return false;
  44. }
  45. return startValue.valueOf() > endValue.valueOf();
  46. },
  47. disabledEndDate(endValue) {
  48. const startValue = this.startValue;
  49. if (!endValue || !startValue) {
  50. return false;
  51. }
  52. return startValue.valueOf() >= endValue.valueOf();
  53. },
  54. handleStartOpenChange(open) {
  55. if (!open) {
  56. this.endOpen = true;
  57. }
  58. },
  59. handleEndOpenChange(open) {
  60. this.endOpen = open;
  61. },
  62. },
  63. };
  64. </script>

DatePicker日期选择框 - 图13

自定义渲染

增加自定义渲染功能,在默认 slot 中,你可以设置任何你想渲染的组件。

  1. <template>
  2. <div>
  3. <a-date-picker v-model="time1" placeholder="Select Time" @change="onChange" @ok="onOk">
  4. <span>{{ time1 ? time1 : 'SelectTime' }}</span>
  5. </a-date-picker>
  6. <br />
  7. <a-range-picker v-model="time2">
  8. <span>
  9. {{ time2 ? time2 : '请选择' }}
  10. </span>
  11. </a-range-picker>
  12. </div>
  13. </template>
  14. <script>
  15. import moment from 'moment';
  16. export default {
  17. data() {
  18. return {
  19. time1: undefined,
  20. time2: undefined,
  21. };
  22. },
  23. methods: {
  24. onChange(value, dateString) {
  25. console.log('Selected Time: ', value);
  26. console.log('Formatted Selected Time: ', dateString);
  27. },
  28. onOk(value) {
  29. console.log('onOk: ', value);
  30. },
  31. clearTime() {
  32. this.time1 = undefined;
  33. },
  34. },
  35. };
  36. </script>

API

日期类组件包括以下四种形式。

  • DatePicker
  • MonthPicker
  • RangePicker
  • WeekPicker

国际化配置

默认配置为 en-US,如果你需要设置其他语言,推荐在入口处使用我们提供的国际化组件,详见:ConfigProvider 国际化

如有特殊需求(仅修改单一组件的语言),请使用 locale 参数,参考:默认配置

  1. <template>
  2. <a-date-picker :locale="locale" />
  3. </template>
  4. <script>
  5. import locale from 'ant-design-vue/es/date-picker/locale/zh_CN';
  6. export default {
  7. data() {
  8. return {
  9. locale,
  10. };
  11. },
  12. };
  13. </script>

**注意:**DatePicker、MonthPicker、RangePicker、WeekPicker 部分 locale 是从 value 中读取,所以请先正确设置 moment 的 locale。

  1. <template>
  2. <a-date-picker :defaultValue="moment('2015-01-01', 'YYYY-MM-DD')" />
  3. </template>
  4. <script>
  5. // 默认语言为 en-US,如果你需要设置其他语言,推荐在入口文件全局设置 locale
  6. import moment from 'moment';
  7. import 'moment/locale/zh-cn';
  8. export default {
  9. data() {
  10. return {
  11. moment,
  12. };
  13. },
  14. };
  15. </script>

共同的 API

以下 API 为 DatePicker、MonthPicker、RangePicker, WeekPicker 共享的 API。

参数说明类型默认值版本
allowClear是否显示清除按钮booleantrue-
autoFocus自动获取焦点booleanfalse-
dateRender作用域插槽,自定义日期单元格的内容slot=”dateRender” slot-scope=”current, today”--
disabled禁用booleanfalse-
disabledDate不可选择的日期(currentDate: moment) => boolean-
getCalendarContainer定义浮层的容器,默认为 body 上新建 divfunction(trigger)-
locale国际化配置object默认配置-
mode日期面板的状态(设置后无法选择年份/月份?time|date|month|year|decade‘date’-
open控制弹层是否展开boolean--
placeholder输入框提示文字string|RangePicker[]--
popupStyle额外的弹出日历样式object{}-
dropdownClassName额外的弹出日历 classNamestring--
size输入框大小,large 高度为 40px,small 为 24px,默认是 32pxstring-
suffixIcon自定义的选择框后缀图标VNode | slot--
inputReadOnly设置输入框为只读(避免在移动设备上打开虚拟键盘)boolean-1.5.4
align该值将合并到 placement 的配置中,设置参考 dom-alignObject1.5.4
valueFormat可选,绑定值的格式,对 value、defaultValue、defaultPickerValue 起作用。不指定则绑定值为 moment 对象string,具体格式-1.5.4

共有的事件

事件名称说明回调参数
openChange弹出日历和关闭日历的回调function(status)
panelChange日期面板变化时的回调function(value, mode)

共同的方法

名称描述
blur()移除焦点
focus()获取焦点

DatePicker

参数说明类型默认值
defaultValue默认日期moment
defaultPickerValue默认面板日期moment
disabledTime不可选择的时间function(date)
format设置日期格式,为数组时支持多格式匹配,展示以第一个为准。配置参考 moment.jsstring | string[]“YYYY-MM-DD”
renderExtraFooter在面板中添加额外的页脚slot=”renderExtraFooter” slot-scope=”mode”-
showTime增加时间选择功能Object|booleanTimePicker Options
showTime.defaultValue设置用户选择日期时默认的时分秒momentmoment()
showToday是否展示“今天”按钮booleantrue
value(v-model)日期moment

DatePicker 事件

事件名称说明回调参数
change时间发生变化的回调function(date: moment | string, dateString: string)
ok点击确定按钮的回调function()

MonthPicker

参数说明类型默认值
defaultValue默认日期moment
defaultPickerValue默认面板日期moment
format展示的日期格式,配置参考 moment.jsstring“YYYY-MM”
monthCellContentRender自定义的月份内容渲染方法slot=”monthCellContentRender” slot-scope=”date, locale”-
renderExtraFooter在面板中添加额外的页脚slot=”renderExtraFooter” slot-scope=”mode”-
value(v-model)日期moment

MonthPicker 事件

事件名称说明回调参数
change时间发生变化的回调,发生在用户选择时间时function(date: moment | string, dateString: string)

WeekPicker

参数说明类型默认值
defaultValue默认日期moment-
defaultPickerValue默认面板日期moment
format展示的日期格式,配置参考 moment.jsstring“YYYY-wo”
value(v-model)日期moment-
renderExtraFooter在面板中添加额外的页脚slot=”renderExtraFooter” slot-scope=”mode”-

WeekPicker 事件

事件名称说明回调参数
change时间发生变化的回调,发生在用户选择时间时function(date: moment | string, dateString: string)

RangePicker

参数说明类型默认值版本
defaultValue默认日期moment[]
defaultPickerValue默认面板日期moment[]
disabledTime不可选择的时间function(dates: [moment, moment], partial: ‘start’|’end’)
format展示的日期格式string“YYYY-MM-DD HH:mm:ss”
ranges预设时间范围快捷选择{ [range: string]: moment[] } | { [range: string]: () => moment[] }
renderExtraFooter在面板中添加额外的页脚slot=”renderExtraFooter” slot-scope=”mode”-
separator设置分隔符string‘~’1.5.0
showTime增加时间选择功能Object|booleanTimePicker Options
showTime.defaultValue设置用户选择日期时默认的时分秒moment[][moment(), moment()]
value(v-model)日期moment[]

RangePicker 事件

事件名称说明回调参数
calendarChange待选日期发生变化的回调function(dates: [moment, moment] | [string, string], dateStrings: [string, string])
change日期范围发生变化的回调function(dates: [moment, moment] | [string, string], dateStrings: [string, string])
ok点击确定按钮的回调function(dates: [moment, moment] | [string, string])