DatePicker 日期选择框

代码演示
~
基本用法

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

<template>
  <a-space direction="vertical">
    <a-date-picker v-model:value="value1" />
    <a-month-picker v-model:value="value2" placeholder="Select month" />
    <a-range-picker v-model:value="value3" />
    <a-week-picker v-model:value="value4" placeholder="Select week" />
  </a-space>
</template>
<script lang="ts">
import { defineComponent, ref } from 'vue';
import { Moment } from 'moment';
export default defineComponent({
  setup() {
    return {
      value1: ref<Moment>(),
      value2: ref<Moment>(),
      value3: ref<Moment[]>([]),
      value4: ref<Moment>(),
    };
  },
});
</script>
~
日期时间选择

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

<template>
  <a-space direction="vertical">
    <a-date-picker show-time placeholder="Select Time" @change="onChange" @ok="onOk" />
    <a-range-picker
      :show-time="{ format: 'HH:mm' }"
      format="YYYY-MM-DD HH:mm"
      :placeholder="['Start Time', 'End Time']"
      @change="onChange"
      @ok="onOk"
    />
  </a-space>
</template>
<script lang="ts">
import { Moment } from 'moment';
import { defineComponent } from 'vue';
export default defineComponent({
  setup() {
    const onChange = (value: Moment[], dateString: string[]) => {
      console.log('Selected Time: ', value);
      console.log('Formatted Selected Time: ', dateString);
    }; 
    const onOk = (value: Moment[]) => {
      console.log('onOk: ', value);
    }; 
    return {
      onChange,
      onOk,
    };
  },
});
</script>
~
不可选择日期和时间

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

<template>
  <a-space direction="vertical">
    <a-date-picker
      v-model:value="value1"
      format="YYYY-MM-DD HH:mm:ss"
      :disabled-date="disabledDate"
      :disabled-time="disabledDateTime"
      :show-time="{ defaultValue: moment('00:00:00', 'HH:mm:ss') }"
    />
    <a-month-picker
      v-model:value="value2"
      :disabled-date="disabledDate"
      placeholder="Select month"
    />
    <a-range-picker
      style="width: 400px"
      v-model:value="value3"
      :disabled-date="disabledDate"
      :disabled-time="disabledRangeTime"
      :show-time="{
        hideDisabledOptions: true,
        defaultValue: [moment('00:00:00', 'HH:mm:ss'), moment('11:59:59', 'HH:mm:ss')],
      }"
      format="YYYY-MM-DD HH:mm:ss"
    />
  </a-space>
</template>
<script lang="ts">
import moment, { Moment } from 'moment';
import { defineComponent, ref } from 'vue';
export default defineComponent({
  setup() {
    const range = (start: number, end: number) => {
      const result = []; 
      for (let i = start; i < end; i++) {
        result.push(i);
      } 
      return result;
    }; 
    const disabledDate = (current: Moment) => {
      // Can not select days before today and today
      return current && current < moment().endOf('day');
    }; 
    const disabledDateTime = () => {
      return {
        disabledHours: () => range(0, 24).splice(4, 20),
        disabledMinutes: () => range(30, 60),
        disabledSeconds: () => [55, 56],
      };
    }; 
    const disabledRangeTime = (_: Moment[], type: 'start' | 'end') => {
      if (type === 'start') {
        return {
          disabledHours: () => range(0, 60).splice(4, 20),
          disabledMinutes: () => range(30, 60),
          disabledSeconds: () => [55, 56],
        };
      }
      return {
        disabledHours: () => range(0, 60).splice(20, 4),
        disabledMinutes: () => range(0, 31),
        disabledSeconds: () => [55, 56],
      };
    }; 
    return {
      moment,
      value1: ref<Moment>(),
      value2: ref<Moment>(),
      value3: ref<Moment[]>([]),
      disabledDate,
      disabledDateTime,
      disabledRangeTime,
    };
  },
});
</script>
~
~
预设范围

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

<template>
  <a-space direction="vertical">
    <a-range-picker v-model:value="value1" :ranges="ranges" />
    <a-range-picker
      style="width: 400px"
      v-model:value="value2"
      :ranges="ranges"
      show-time
      format="YYYY/MM/DD HH:mm:ss"
    />
  </a-space>
</template>
<script lang="ts">
import moment, { Moment } from 'moment';
import { defineComponent, ref } from 'vue';
export default defineComponent({
  setup() {
    return {
      value1: ref<Moment[]>([]),
      value2: ref<Moment[]>([]),
      ranges: { Today: [moment(), moment()], 'This Month': [moment(), moment().endOf('month')] },
    };
  },
});
</script>
~
三种大小

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

<template>
  <a-space direction="vertical">
    <a-radio-group v-model:value="size">
      <a-radio-button value="large">Large</a-radio-button>
      <a-radio-button value="default">Default</a-radio-button>
      <a-radio-button value="small">Small</a-radio-button>
    </a-radio-group>
    <a-date-picker :size="size" />
    <a-month-picker :size="size" placeholder="Select Month" />
    <a-range-picker :size="size" />
    <a-week-picker :size="size" placeholder="Select Week" />
  </a-space>
</template>
<script lang="ts">
import moment from 'moment';
import { defineComponent, ref } from 'vue';
export default defineComponent({
  setup() {
    return {
      size: ref<string>('default'),
      moment,
    };
  },
});
</script>
~
受控面板

通过组合 mode 与 onPanelChange 控制要展示的面板。

<template>
  <a-space direction="vertical">
    <a-date-picker
      :mode="mode1"
      show-time
      @openChange="handleOpenChange1"
      @panelChange="handlePanelChange1"
    />
    <a-range-picker
      :placeholder="['Start month', 'End month']"
      format="YYYY-MM"
      :value="value"
      :mode="mode2"
      @panelChange="handlePanelChange2"
      @change="handleChange"
    />
  </a-space>
</template>
<script lang="ts">
import { Moment } from 'moment';
import { defineComponent, ref } from 'vue';
export default defineComponent({
  setup() {
    const mode1 = ref<string>('time');
    const mode2 = ref<string[]>(['month', 'month']);
    const value = ref<Moment[]>([]); 
    const handleOpenChange1 = (open: boolean) => {
      if (open) {
        mode1.value = 'time';
      }
    }; 
    const handleChange = (val: Moment[]) => {
      value.value = val;
    }; 
    const handlePanelChange1 = (val: Moment[], mode: string) => {
      mode1.value = mode;
    }; 
    const handlePanelChange2 = (val: Moment[], mode: string[]) => {
      value.value = val;
      mode2.value = [
        mode[0] === 'date' ? 'month' : mode[0],
        mode[1] === 'date' ? 'month' : mode[1],
      ];
    }; 
    return {
      mode1,
      mode2,
      value,
      handleOpenChange1,
      handleChange,
      handlePanelChange1,
      handlePanelChange2,
    };
  },
});
</script>
SelectTime
请选择
自定义渲染

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

<template>
  <a-space direction="vertical">
    <a-date-picker v-model:value="time1" placeholder="Select Time" @ok="onOk">
      <span>{{ time1 ? time1.toString() : 'SelectTime' }}</span>
    </a-date-picker>
    <a-range-picker v-model:value="time2">
      <span>
        {{ time2 ? time2.toString() : '请选择' }}
      </span>
    </a-range-picker>
  </a-space>
</template>
<script lang="ts">
import moment, { Moment } from 'moment';
import { defineComponent, ref } from 'vue';
export default defineComponent({
  setup() {
    const time1 = ref<Moment>();
    const time2 = ref<Moment>(); 
    const onOk = (value: Moment) => {
      console.log('onOk: ', value);
    }; 
    const clearTime = () => {
      time1.value = undefined;
    }; 
    return {
      time1,
      time2,
      moment,
      onOk,
      clearTime,
    };
  },
});
</script>
~
日期格式

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

<template>
  <a-space direction="vertical">
    <a-date-picker v-model:value="value1" :format="dateFormat" />
    <a-date-picker v-model:value="value2" :format="dateFormatList" />
    <a-month-picker v-model:value="value3" :format="monthFormat" />
    <a-range-picker v-model:value="value4" :format="dateFormat" />
  </a-space>
</template>
<script lang="ts">
import moment, { Moment } from 'moment';
import { defineComponent, ref } from 'vue';
export default defineComponent({
  setup() {
    const dateFormat = 'YYYY/MM/DD';
    const monthFormat = 'YYYY/MM';
    const dateFormatList = ['DD/MM/YYYY', 'DD/MM/YY'];
    return {
      value1: ref<Moment>(moment('2015/01/01', dateFormat)),
      value2: ref<Moment>(moment('01/01/2015', dateFormatList[0])),
      value3: ref<Moment>(moment('2015/01', monthFormat)),
      value4: ref<Moment[]>([moment('2015/01/01', dateFormat), moment('2015/01/01', dateFormat)]),
      dateFormat,
      monthFormat,
      dateFormatList,
      moment,
    };
  },
});
</script>
~
禁用

选择框的不可用状态。

<template>
  <a-space direction="vertical">
    <a-date-picker v-model:value="value1" />
    <a-month-picker v-model:value="value2" disabled />
    <a-range-picker v-model:value="value3" disabled />
  </a-space>
</template>
<script lang="ts">
import moment from 'moment';
import { defineComponent, ref } from 'vue';
export default defineComponent({
  setup() {
    const dateFormat = 'YYYY-MM-DD';
    return {
      value1: ref<moment.Moment>(moment('2015-06-06', dateFormat)),
      value2: ref<moment.Moment>(moment('2015-06', 'YYYY-MM')),
      value3: ref<moment.Moment[]>([
        moment('2015-06-06', dateFormat),
        moment('2015-06-06', dateFormat),
      ]),
    };
  },
});
</script>
~
选择不超过七天的范围

这里举例如何用 onCalendarChange 和 disabledDate 来限制动态的日期区间选择。

<template>
  <a-range-picker
    v-model:value="value"
    :disabledDate="disabledDate"
    @change="onChange"
    @openChange="onOpenChange"
    @calendarChange="onCalendarChange"
  />
</template>
<script lang="ts">
import { Moment } from 'moment';
import { defineComponent, ref } from 'vue';
export default defineComponent({
  setup() {
    const dates = ref<Moment[]>([]);
    const value = ref<Moment[]>(); 
    const disabledDate = (current: Moment) => {
      if (!dates.value || dates.value.length === 0) {
        return false;
      }
      const diffDate = current.diff(dates.value[0], 'days');
      return Math.abs(diffDate) > 7;
    }; 
    const onOpenChange = (open: boolean) => {
      if (open) {
        dates.value = [];
      }
    }; 
    const onChange = (val: Moment[]) => {
      value.value = val;
    }; 
    const onCalendarChange = (val: Moment[]) => {
      dates.value = val;
    }; 
    return {
      dates,
      value,
      disabledDate,
      onOpenChange,
      onChange,
      onCalendarChange,
    };
  },
});
</script>
~
定制日期单元格

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

<template>
  <a-space direction="vertical">
    <a-date-picker v-model:value="value1">
      <template #dateRender="{ current, today }">
        <div class="ant-calendar-date" :style="getCurrentStyle(current, today)">
          {{ current.date() }}
        </div>
      </template>
    </a-date-picker>
    <a-range-picker v-model:value="value2">
      <template #dateRender="{ current }">
        <div class="ant-calendar-date" :style="getCurrentStyle(current)">
          {{ current.date() }}
        </div>
      </template>
    </a-range-picker>
    <a-week-picker v-model:value="value3">
      <template #dateRender="{ current }">
        <div class="ant-calendar-date" :style="getCurrentStyle(current)">
          {{ current.date() }}
        </div>
      </template>
    </a-week-picker>
  </a-space>
</template>
<script lang="ts">
import { Moment } from 'moment';
import { CSSProperties, defineComponent, ref } from 'vue';
export default defineComponent({
  setup() {
    const getCurrentStyle = (current: Moment) => {
      const style: CSSProperties = {}; 
      if (current.date() === 1) {
        style.border = '1px solid #1890ff';
        style.borderRadius = '50%';
      } 
      return style;
    };
    return {
      value1: ref<Moment>(),
      value2: ref<Moment[]>([]),
      value3: ref<Moment>(),
      getCurrentStyle,
    };
  },
});
</script>
自定义日期范围选择

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

  • 通过设置 disabledDate 方法，来约束开始和结束日期。
  • 通过 open openChange 来优化交互。
<template>
  <a-space direction="vertical">
    <a-date-picker
      v-model:value="startValue"
      :disabled-date="disabledStartDate"
      show-time
      format="YYYY-MM-DD HH:mm:ss"
      placeholder="Start"
      @openChange="handleStartOpenChange"
    />
    <a-date-picker
      v-model:value="endValue"
      :disabled-date="disabledEndDate"
      show-time
      format="YYYY-MM-DD HH:mm:ss"
      placeholder="End"
      :open="endOpen"
      @openChange="handleEndOpenChange"
    />
  </a-space>
</template>
<script lang="ts">
import { Moment } from 'moment';
import { defineComponent, ref, watch } from 'vue';
export default defineComponent({
  setup() {
    const startValue = ref<Moment | undefined>();
    const endValue = ref<Moment>();
    const endOpen = ref<boolean>(false); 
    const disabledStartDate = (startValue: Moment) => {
      if (!startValue || !endValue.value) {
        return false;
      } 
      return startValue.valueOf() > endValue.value.valueOf();
    }; 
    const disabledEndDate = (endValue: Moment) => {
      if (!endValue || !startValue.value) {
        return false;
      } 
      return startValue.value.valueOf() >= endValue.valueOf();
    }; 
    const handleStartOpenChange = (open: boolean) => {
      if (!open) {
        endOpen.value = true;
      }
    }; 
    const handleEndOpenChange = (open: boolean) => {
      endOpen.value = open;
    }; 
    watch(startValue, () => {
      console.log('startValue', startValue.value);
    }); 
    watch(endValue, () => {
      console.log('endValue', endValue.value);
    }); 
    return {
      startValue,
      endValue,
      endOpen,
      disabledStartDate,
      disabledEndDate,
      handleStartOpenChange,
      handleEndOpenChange,
    };
  },
});
</script>
~
ab
ab
~ ab
ab
后缀图标

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

<template>
  <a-space direction="vertical">
    <a-date-picker @change="onChange">
      <template #suffixIcon>
        <SmileOutlined />
      </template>
    </a-date-picker>
    <a-month-picker @change="onChange" placeholder="Select month">
      <template #suffixIcon>
        <SmileOutlined />
      </template>
    </a-month-picker>
    <a-range-picker @change="onChange">
      <template #suffixIcon>
        <SmileOutlined />
      </template>
    </a-range-picker>
    <a-week-picker @change="onChange" placeholder="Select week">
      <template #suffixIcon>
        <SmileOutlined />
      </template>
    </a-week-picker>
    <a-date-picker suffix-icon="ab" @change="onChange" />
    <a-month-picker suffix-icon="ab" placeholder="Select month" @change="onChange" />
    <a-range-picker suffix-icon="ab" @change="onChange" />
    <a-week-picker suffix-icon="ab" placeholder="Select week" @change="onChange" />
  </a-space>
</template>
<script lang="ts">
import { SmileOutlined } from '@ant-design/icons-vue';
import { Moment } from 'moment';
import { defineComponent } from 'vue';
export default defineComponent({
  components: {
    SmileOutlined,
  },
  setup() {
    const onChange = (date: Moment, dateString: string[]) => {
      console.log(date, dateString);
    }; 
    return {
      onChange,
    };
  },
});
</script>

API#

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

国际化配置

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

如有特殊需求（仅修改单一组件的语言），请使用 locale 参数，参考：默认配置。

<template>
  <a-date-picker v-model:value="value" :locale="locale" />
</template>
<script>
  import locale from 'ant-design-vue/es/date-picker/locale/zh_CN';
  import { defineComponent } from 'vue';
  export default defineComponent({
    setup() {
      return {
        locale,
        value: null,
      };
    },
  });
</script>

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

<template>
  <a-date-picker v-model:value="value" />
</template>
<script>
  // 默认语言为 en-US，如果你需要设置其他语言，推荐在入口文件全局设置 locale
  import moment from 'moment';
  import 'moment/dist/locale/zh-cn';
  import { defineComponent } from 'vue';
  export default defineComponent({
    setup() {
      return {
        value: moment('2015-01-01', 'YYYY-MM-DD')
        moment,
      };
    },
  });
</script>

共同的 API

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

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

共有的事件

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

共同的方法

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

DatePicker

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

DatePicker 事件

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

MonthPicker

参数 说明 类型 默认值
defaultPickerValue 默认面板日期 moment 无
format 展示的日期格式，配置参考 moment.js string "YYYY-MM"
monthCellContentRender 自定义的月份内容渲染方法 #monthCellContentRender="{current, locale}" -
renderExtraFooter 在面板中添加额外的页脚 #renderExtraFooter="mode" -
value(v-model) 日期 moment 无

MonthPicker 事件

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

WeekPicker

参数 说明 类型 默认值
defaultPickerValue 默认面板日期 moment 无
format 展示的日期格式，配置参考 moment.js string "YYYY-wo"
value(v-model) 日期 moment -
renderExtraFooter 在面板中添加额外的页脚 #renderExtraFooter="mode" -

WeekPicker 事件

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

RangePicker

参数 说明 类型 默认值 版本
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 在面板中添加额外的页脚 #renderExtraFooter="mode" -
separator 设置分隔符 string '~' 1.5.0
showTime 增加时间选择功能 Object|boolean TimePicker 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])