DatePicker 日期选择器

输入或选择日期的控件。

何时使用

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

代码演示

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

<template>
  <f-config-provider :locale="zhCN">
    <div class="f-date-docx-box">
      <f-date-picker v-model:value="value1" />
      <f-date-picker v-model:value="value2" picker="week" />
      <f-date-picker v-model:value="value3" picker="month" />
      <f-date-picker v-model:value="value4" picker="quarter" />
      <f-date-picker v-model:value="value5" picker="year" />
    </div>
  </f-config-provider>
</template>
<script lang="ts">
import { defineComponent, ref } from 'vue'
import type { Dayjs } from 'dayjs'
import zhCN from 'ant-design-vue/lib/locale/zh_CN'
import dayjs from 'dayjs'
import 'dayjs/locale/zh-cn'
dayjs.locale('zh')
export default defineComponent({
  setup() {
    return {
      value1: ref<Dayjs>(),
      value2: ref<Dayjs>(),
      value3: ref<Dayjs>(),
      value4: ref<Dayjs>(),
      value5: ref<Dayjs>(),
      zhCN,
    }
  },
})
</script>
<style>
.f-date-docx-box .fs-picker {
  margin-right: 10px;
}
</style>

范围选择器
通过设置 picker 属性，指定范围选择器类型。

<template>
  <f-config-provider :locale="zhCN">
    <div class="f-date-docx-box">
      <f-range-picker v-model:value="value1" />
      <f-range-picker v-model:value="value2" show-time />
      <f-range-picker v-model:value="value3" picker="week" />
      <f-range-picker v-model:value="value4" picker="month" />
      <f-range-picker v-model:value="value5" picker="year" />
    </div>
  </f-config-provider>
</template>
<script lang="ts">
import { defineComponent, ref } from 'vue'
import type { Dayjs } from 'dayjs'
import zhCN from 'ant-design-vue/lib/locale/zh_CN'
import dayjs from 'dayjs'
import 'dayjs/locale/zh-cn'
dayjs.locale('zh')
export default defineComponent({
  setup() {
    return {
      value1: ref<Dayjs>(),
      value2: ref<Dayjs>(),
      value3: ref<Dayjs>(),
      value4: ref<Dayjs>(),
      value5: ref<Dayjs>(),
      zhCN,
    }
  },
})
</script>
<style>
.f-date-docx-box .fs-picker {
  margin-right: 10px;
  margin-bottom: 10px;
}
</style>

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

<template>
  <f-config-provider :locale="zhCN">
    <div class="f-date-docx-box">
      <f-date-picker v-model:value="value1" :format="dateFormat" />
      <f-date-picker v-model:value="value2" :format="dateFormatList" />
      <f-date-picker v-model:value="value3" :format="monthFormat" picker="month" />
      <f-range-picker v-model:value="value4" :format="dateFormat" />
      <f-date-picker v-model:value="value5" :format="customFormat" />
      <f-date-picker v-model:value="value6" :format="customWeekStartEndFormat" picker="week" />
    </div>
  </f-config-provider>
</template>
<script lang="ts">
import { defineComponent, ref } from 'vue'
import type { Dayjs } from 'dayjs'
import zhCN from 'ant-design-vue/lib/locale/zh_CN'
import dayjs from 'dayjs'
import 'dayjs/locale/zh-cn'
dayjs.locale('zh')
export default defineComponent({
  setup() {
    const dateFormat = 'YYYY/MM/DD'
    const weekFormat = 'MM/DD'
    const monthFormat = 'YYYY/MM'
    const dateFormatList = ['DD/MM/YYYY', 'DD/MM/YY']

    const customWeekStartEndFormat = value =>
      `${dayjs(value).startOf('week').format(weekFormat)} ~ ${dayjs(value).endOf('week').format(weekFormat)}`
    return {
      value1: ref<Dayjs>(dayjs('2015/01/01', dateFormat)),
      value2: ref<Dayjs>(dayjs('01/01/2015', dateFormatList[0])),
      value3: ref<Dayjs>(dayjs('2015/01', monthFormat)),
      value4: ref<[Dayjs, Dayjs]>([dayjs('2015/01/01', dateFormat), dayjs('2015/01/01', dateFormat)]),
      value5: ref<Dayjs>(dayjs('2015/01/01', dateFormat)),
      value6: ref<Dayjs>(dayjs()),
      dateFormat,
      monthFormat,
      dateFormatList,
      customWeekStartEndFormat,
      customFormat: value => `custom format: ${value.format(dateFormat)}`,
      zhCN,
    }
  },
})
</script>
<style>
.f-date-docx-box .fs-picker {
  margin-right: 10px;
}
</style>

禁用
选择框的不可用状态。

<template>
  <f-config-provider :locale="zhCN">
    <div class="f-date-docx-box">
      <f-date-picker v-model:value="value1" />
      <f-date-picker v-model:value="value2" disabled picker="month" />
      <f-range-picker v-model:value="value3" disabled />
      <f-range-picker v-model:value="value4" :disabled="[false, true]" />
    </div>
  </f-config-provider>
</template>
<script lang="ts">
import { defineComponent, ref } from 'vue'
import type { Dayjs } from 'dayjs'
import zhCN from 'ant-design-vue/lib/locale/zh_CN'
import dayjs from 'dayjs'
import 'dayjs/locale/zh-cn'
dayjs.locale('zh')
export default defineComponent({
  setup() {
    const dateFormat = 'YYYY-MM-DD'
    return {
      zhCN,
      value1: ref<Dayjs>(dayjs('2015-06-06', dateFormat)),
      value2: ref<Dayjs>(dayjs('2015-06', 'YYYY-MM')),
      value3: ref<[Dayjs, Dayjs]>([dayjs('2015-06-06', dateFormat), dayjs('2015-06-06', dateFormat)]),
      value4: ref<[Dayjs, Dayjs]>([dayjs('2019-09-03', dateFormat), dayjs('2019-11-22', dateFormat)]),
    }
  },
})
</script>
<style>
.f-date-docx-box .fs-picker {
  margin-right: 10px;
}
</style>

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

<template>
  <f-config-provider :locale="zhCN">
    <div class="f-date-docx-box">
      <f-date-picker show-time placeholder="Select Time" @change="onChange" @ok="onOk" />
      <f-range-picker
        :show-time="{ format: 'HH:mm' }"
        format="YYYY-MM-DD HH:mm"
        :placeholder="['Start Time', 'End Time']"
        @change="onRangeChange"
        @ok="onRangeOk"
      />
    </div>
  </f-config-provider>
</template>
<script lang="ts">
import { defineComponent, ref } from 'vue'
import type { Dayjs } from 'dayjs'
import zhCN from 'ant-design-vue/lib/locale/zh_CN'
import dayjs from 'dayjs'
import 'dayjs/locale/zh-cn'
dayjs.locale('zh')
export default defineComponent({
  setup() {
    const onChange = (value: Dayjs, dateString: string) => {
      console.log('Selected Time: ', value)
      console.log('Formatted Selected Time: ', dateString)
    }

    const onOk = (value: Dayjs) => {
      console.log('onOk: ', value)
    }

    const onRangeChange = (value: [Dayjs, Dayjs], dateString: [string, string]) => {
      console.log('Selected Time: ', value)
      console.log('Formatted Selected Time: ', dateString)
    }

    const onRangeOk = (value: [Dayjs, Dayjs]) => {
      console.log('onOk: ', value)
    }

    return {
      zhCN,
      onChange,
      onOk,
      onRangeChange,
      onRangeOk,
    }
  },
})
</script>
<style>
.f-date-docx-box .fs-picker {
  margin-right: 10px;
}
</style>

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

<template>
  <f-config-provider :locale="zhCN">
    <div class="f-date-docx-box">
      <f-date-picker
        v-model:value="value1"
        format="YYYY-MM-DD HH:mm:ss"
        :disabled-date="disabledDate"
        :disabled-time="disabledDateTime"
        :show-time="{ defaultValue: dayjs('00:00:00', 'HH:mm:ss') }"
      />
      <f-date-picker v-model:value="value2" :disabled-date="disabledDate" picker="month" />
      <f-range-picker v-model:value="value3" :disabled-date="disabledDate" />
      <f-range-picker
        v-model:value="value4"
        style="width: 400px"
        :disabled-date="disabledDate"
        :disabled-time="disabledRangeTime"
        :show-time="{
          hideDisabledOptions: true,
          defaultValue: [dayjs('00:00:00', 'HH:mm:ss'), dayjs('11:59:59', 'HH:mm:ss')],
        }"
        format="YYYY-MM-DD HH:mm:ss"
      />
    </div>
  </f-config-provider>
</template>
<script lang="ts">
import { defineComponent, ref } from 'vue'
import type { Dayjs } from 'dayjs'
import zhCN from 'ant-design-vue/lib/locale/zh_CN'
import dayjs from 'dayjs'
import 'dayjs/locale/zh-cn'
dayjs.locale('zh')
export default defineComponent({
  setup() {
    const range = (start: number, end: number) => {
      const result: number[] = []

      for (let i = start; i < end; i++) {
        result.push(i)
      }

      return result
    }

    const disabledDate = (current: Dayjs) => {
      // Can not select days before today and today
      return current && current < dayjs().endOf('day')
    }

    const disabledDateTime = () => {
      return {
        disabledHours: () => range(0, 24).splice(4, 20),
        disabledMinutes: () => range(30, 60),
        disabledSeconds: () => [55, 56],
      }
    }

    const disabledRangeTime = (_: Dayjs, 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 {
      zhCN,
      dayjs,
      value1: ref<Dayjs>(),
      value2: ref<Dayjs>(),
      value3: ref<[Dayjs, Dayjs]>(),
      value4: ref<[Dayjs, Dayjs]>(),
      disabledDate,
      disabledDateTime,
      disabledRangeTime,
    }
  },
})
</script>
<style>
.f-date-docx-box .fs-picker {
  margin-right: 10px;
}
</style>

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

<template>
  <f-config-provider :locale="zhCN">
    <div class="f-date-docx-box">
      <div>
        <f-radio-group v-model:value="size">
          <f-radio value="large">Large</f-radio>
          <f-radio value="default">Default</f-radio>
          <f-radio value="small">Small</f-radio>
        </f-radio-group>
      </div>
      <f-date-picker :size="size" />
      <f-date-picker :size="size" placeholder="Select Month" picker="month" />
      <f-range-picker :size="size" />
      <f-date-picker :size="size" placeholder="Select Week" picker="week" />
    </div>
  </f-config-provider>
</template>
<script lang="ts">
import { defineComponent, ref } from 'vue'
import zhCN from 'ant-design-vue/lib/locale/zh_CN'
import dayjs from 'dayjs'
import 'dayjs/locale/zh-cn'
dayjs.locale('zh')
export default defineComponent({
  setup() {
    return {
      size: ref<any>('default'),
      zhCN,
    }
  },
})
</script>
<style>
.f-date-docx-box .fs-picker {
  margin-right: 10px;
}
</style>

后缀图标
通过 suffixIcon 自定义后缀图标

<template>
  <f-config-provider :locale="zhCN">
    <div class="f-date-docx-box">
      <f-date-picker @change="onChange">
        <template #suffixIcon>
          <SmileOutlined />
        </template>
      </f-date-picker>
      <f-date-picker placeholder="Select month" picker="month" @change="onChange">
        <template #suffixIcon>
          <SmileOutlined />
        </template>
      </f-date-picker>
      <f-range-picker @change="onRangeChange">
        <template #suffixIcon>
          <SmileOutlined />
        </template>
      </f-range-picker>
      <f-date-picker placeholder="Select week" picker="week" @change="onChange">
        <template #suffixIcon>
          <SmileOutlined />
        </template>
      </f-date-picker>
      <f-date-picker suffix-icon="ab" @change="onChange" />
      <f-date-picker suffix-icon="ab" placeholder="Select month" picker="month" @change="onChange" />
      <f-range-picker suffix-icon="ab" @change="onRangeChange" />
      <f-date-picker suffix-icon="ab" placeholder="Select week" picker="week" @change="onChange" />
    </div>
  </f-config-provider>
</template>
<script lang="ts">
import { defineComponent, ref } from 'vue'
import { SmileOutlined } from '@ant-design/icons-vue'
import type { Dayjs } from 'dayjs'
import zhCN from 'ant-design-vue/lib/locale/zh_CN'
import dayjs from 'dayjs'
import 'dayjs/locale/zh-cn'
dayjs.locale('zh')
export default defineComponent({
  components: {
    SmileOutlined,
  },
  setup() {
    const onChange = (date: Dayjs | string, dateString: string) => {
      console.log(date, dateString)
    }

    const onRangeChange = (date: [Dayjs, Dayjs], dateString: [string, string]) => {
      console.log(date, dateString)
    }
    return {
      zhCN,
      onChange,
      onRangeChange,
    }
  },
})
</script>
<style>
.f-date-docx-box .fs-picker {
  margin-right: 10px;
}
</style>

共同的 API

以下 API 为 DatePicker、 RangePicker 共享的 API。

参数	说明	类型	默认值	版本
pressLine 新增	组件右上角文本	string
allowClear	是否显示清除按钮	boolean	true
autofocus	自动获取焦点	boolean	false
bordered	是否有边框	boolean	true
dateRender	自定义日期单元格的内容	v-slot:dateRender="{current, today}"	-
disabled	禁用	boolean	false
disabledDate	不可选择的日期	(currentDate: dayjs) => boolean	-
format	设置日期格式，为数组时支持多格式匹配，展示以第一个为准。配置参考 dayjs，支持自定义格式	formatType	YYYY-MM-DD
dropdownClassName	额外的弹出日历 className	string	-
getPopupContainer	定义浮层的容器，默认为 body 上新建 div	function(trigger)	-
inputReadOnly	设置输入框为只读（避免在移动设备上打开虚拟键盘）	boolean	false
locale	国际化配置	object	默认配置	-
mode	日期面板的状态	time | date | month | year | decade	-
nextIcon	自定义下一个图标	slot	-	3.0
open	控制弹层是否展开	boolean	-
picker	设置选择器类型	date | week | month | quarter | year	date	quarter
placeholder	输入框提示文字	string | [string, string]	-
popupStyle	额外的弹出日历样式	CSSProperties	{}
prevIcon	自定义上一个图标	slot	-	3.0
size	输入框大小，large 高度为 40px，small 为 24px，默认是 32px	large | middle | small	-
suffixIcon	自定义的选择框后缀图标	v-slot:suffixIcon	-
superNextIcon	自定义 << 切换图标	slot	-	3.0
superPrevIcon	自定义 >> 切换图标	slot	-	3.0
valueFormat	可选，绑定值的格式，对 value、defaultValue、defaultPickerValue 起作用。不指定则绑定值为 dayjs 对象	string，具体格式	-

共有的事件

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

共同的方法

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

DatePicker

参数	说明	类型	默认值	版本
defaultPickerValue	默认面板日期	dayjs	-
disabledTime	不可选择的时间	function(date)	-
format	展示的日期格式，配置参考 dayjs	formatType	YYYY-MM-DD
renderExtraFooter	在面板中添加额外的页脚	v-slot:renderExtraFooter="mode"	-
showNow	当设定了 showTime 的时候，面板是否显示“此刻”按钮	boolean	-
showTime	增加时间选择功能	Object | boolean	TimePicker Options
showTime.defaultValue	设置用户选择日期时默认的时分秒，例子	dayjs	dayjs()
showToday	是否展示“今天”按钮	boolean	true
value(v-model)	日期	dayjs	-

DatePicker 事件

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

DatePicker[picker=year]

参数	说明	类型	默认值	版本
format	展示的日期格式，配置参考 dayjs	formatType	YYYY

DatePicker[picker=quarter]

参数	说明	类型	默认值	版本
format	展示的日期格式，配置参考 dayjs	formatType	YYYY-\QQ

DatePicker[picker=month]

参数	说明	类型	默认值	版本
format	展示的日期格式，配置参考 dayjs	formatType	YYYY-MM
monthCellRender	自定义的月份内容渲染方法	v-slot:monthCellRender="{current, locale}"	-

DatePicker[picker=week]

参数	说明	类型	默认值	版本
format	展示的日期格式，配置参考 dayjs	formatType	YYYY-wo

RangePicker

参数	说明	类型	默认值	版本
allowEmpty	允许起始项部分为空	[boolean, boolean]	[false, false]
dateRender	自定义日期单元格的内容。	v-slot:dateRender="{current: dayjs, today: dayjs, info: { range: start | end }}"	-
defaultPickerValue	默认面板日期	dayjs[]	-
disabled	禁用起始项	[boolean, boolean]	-
disabledTime	不可选择的时间	function(date: dayjs, partial: start | end)	-
format	展示的日期格式	formatType	YYYY-MM-DD HH:mm:ss
ranges	预设时间范围快捷选择	{ [range: string]: dayjs[] } | { [range: string]: () => dayjs[] }	-
renderExtraFooter	在面板中添加额外的页脚	v-slot:renderExtraFooter="mode"	-
separator	设置分隔符	string | v-slot:separator	<SwapRightOutlined />
showTime	增加时间选择功能	Object|boolean	TimePicker Options
showTime.defaultValue	设置用户选择日期时默认的时分秒，例子	dayjs[]	[dayjs(), dayjs()]
value(v-model)	日期	dayjs[]	-

RangePicker 事件

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