• DatePicker 日期选择框
    • 何时使用
    • 代码演示
      • 基本
      • 定制日期单元格
      • 不可选择日期和时间
      • 禁用
      • 额外的页脚
      • 日期格式
      • 受控面板
      • 预设范围
      • 三种大小
      • 自定义日期范围选择
      • 日期时间选择
      • 自定义渲染
      • 后缀图标
  • API
    • 共同的 API
    • 共有的事件
    • 共同的方法
    • DatePicker
    • DatePicker 事件
    • MonthPicker
    • MonthPicker 事件
    • WeekPicker
    • WeekPicker 事件
    • RangePicker
    • RangePicker 事件

    DatePicker 日期选择框

    输入或选择日期的控件。

    何时使用

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

    代码演示

    DatePicker 日期选择框 - 图1

    基本

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

    1. <template>
    2. <div>
    3. <a-date-picker @change="onChange" />
    4. <br />
    5. <a-month-picker @change="onChange" placeholder="Select month" />
    6. <br />
    7. <a-range-picker @change="onChange" />
    8. <br />
    9. <a-week-picker @change="onChange" placeholder="Select week" />
    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

    定制日期单元格

    使用 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 日期选择框 - 图3

    不可选择日期和时间

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

    1. <template>
    2. <div>
    3. <a-date-picker
    4. format="YYYY-MM-DD HH:mm:ss"
    5. :disabledDate="disabledDate"
    6. :disabledTime="disabledDateTime"
    7. :showTime="{ defaultValue: moment('00:00:00', 'HH:mm:ss') }"
    8. />
    9. <br />
    10. <a-month-picker :disabledDate="disabledDate" placeholder="Select month" />
    11. <br />
    12. <a-range-picker
    13. :disabledDate="disabledDate"
    14. :disabledTime="disabledRangeTime"
    15. :showTime="{
    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 日期选择框 - 图4

    禁用

    选择框的不可用状态。

    1. <template>
    2. <div>
    3. <a-date-picker :defaultValue="moment('2015-06-06', dateFormat)" disabled />
    4. <br />
    5. <a-month-picker :defaultValue="moment('2015-06', 'YYYY-MM')" disabled />
    6. <br />
    7. <a-range-picker
    8. :defaultValue="[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 日期选择框 - 图5

    额外的页脚

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

    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 showTime>
    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 showTime>
    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 日期选择框 - 图6

    日期格式

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

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

    DatePicker 日期选择框 - 图7

    受控面板

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

    1. <template>
    2. <div>
    3. <a-date-picker
    4. :mode="mode1"
    5. showTime
    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 = [
    44. mode[0] === 'date' ? 'month' : mode[0],
    45. mode[1] === 'date' ? 'month' : mode[1],
    46. ];
    47. },
    48. },
    49. };
    50. </script>

    DatePicker 日期选择框 - 图8

    预设范围

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

    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. showTime
    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 日期选择框 - 图9

    三种大小

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

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

    DatePicker 日期选择框 - 图10

    自定义日期范围选择

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

    • 通过设置 disabledDate 方法,来约束开始和结束日期。
    • 通过 open onOpenChange 来优化交互。
    1. <template>
    2. <div>
    3. <a-date-picker
    4. :disabledDate="disabledStartDate"
    5. showTime
    6. format="YYYY-MM-DD HH:mm:ss"
    7. v-model="startValue"
    8. placeholder="Start"
    9. @openChange="handleStartOpenChange"
    10. />
    11. <a-date-picker
    12. :disabledDate="disabledEndDate"
    13. showTime
    14. format="YYYY-MM-DD HH:mm:ss"
    15. placeholder="End"
    16. v-model="endValue"
    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 日期选择框 - 图11

    日期时间选择

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

    1. <template>
    2. <div>
    3. <a-date-picker showTime placeholder="Select Time" @change="onChange" @ok="onOk" />
    4. <br />
    5. <a-range-picker
    6. :showTime="{ 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 日期选择框 - 图12

    自定义渲染

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

    1. <template>
    2. <div>
    3. <a-date-picker placeholder="Select Time" v-model="time1" @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>

    DatePicker 日期选择框 - 图13

    后缀图标

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

    <template>
      <div>
        <a-date-picker @change="onChange">
          <a-icon slot="suffixIcon" type="smile" />
        </a-date-picker>
        <br />
        <a-month-picker @change="onChange" placeholder="Select month">
          <a-icon slot="suffixIcon" type="smile" />
        </a-month-picker>
        <br />
        <a-range-picker @change="onChange">
          <a-icon slot="suffixIcon" type="smile" />
        </a-range-picker>
        <br />
        <a-week-picker @change="onChange" placeholder="Select week">
          <a-icon slot="suffixIcon" type="smile" />
        </a-week-picker>
        <br />
        <a-date-picker suffixIcon="ab" @change="onChange" />
        <br />
        <a-month-picker suffixIcon="ab" @change="onChange" placeholder="Select month" />
        <br />
        <a-range-picker suffixIcon="ab" @change="onChange" />
        <br />
        <a-week-picker suffixIcon="ab" @change="onChange" placeholder="Select week" />
      </div>
    </template>
    <script>
      export default {
        methods: {
          onChange(date, dateString) {
            console.log(date, dateString);
          },
        },
      };
    </script>
    

    API

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

    • DatePicker
    • MonthPicker
    • RangePicker
    • WeekPicker

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

    // 默认语言为 en-US,如果你需要设置其他语言,推荐在入口文件全局设置 locale import moment from
    'moment'; import 'moment/locale/zh-cn'; moment.locale('zh-cn');
    
    <a-date-picker :defaultValue="moment('2015-01-01', 'YYYY-MM-DD')" />
    

    共同的 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默认配置
    open控制弹层是否展开boolean-
    placeholder输入框提示文字string|RangePicker[]-
    popupStyle额外的弹出日历样式object{}
    dropdownClassName额外的弹出日历 classNamestring-
    size输入框大小,large 高度为 40px,small 为 24px,默认是 32pxstring
    suffixIcon自定义的选择框后缀图标VNode | slot-

    共有的事件

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

    共同的方法

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

    DatePicker

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

    DatePicker 事件

    事件名称说明回调参数
    change时间发生变化的回调function(date: moment, 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, 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, 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"-
    showTime增加时间选择功能Object|booleanTimePicker Options
    showTime.defaultValue设置用户选择日期时默认的时分秒moment[][moment(), moment()]
    value(v-model)日期moment[]

    RangePicker 事件

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