docs_vue2/one/docs/components/date-picker.md

DatePicker 日期选择

示例

单日选择

默认情况下，在下拉浮层中单击日期可以选中一个日期。可以配置 clearable 属性来允许清除已选值，用 placeholder 属性来配置未选择时的占位文本。

日期范围选择

配置 range 属性时，可以在下拉浮层中选择一个日期范围。

设置快捷选项

选择日期范围时，可以通过配置 shortcuts 属性来提供快捷选项。

API

属性

名称	类型	默认值	描述
type	string	'date'	日历的类型，可用值为 'date'/'month'/'year'，分别对应日期/月/年视图。
range	boolean	false	是否选择日期范围。
selected	`Date	Array`	-
today	Date	new Date()	「今天」的日期。
week-start	number	calendar.weekStart	一周的起始。可进行全局配置。
fill-month	boolean	true	当只有一个面板时，是否要在当前月份面板显示非本月日期。
date-class	`string	Array	Object
disabled-date	function(Date, Date=): boolean=	() => false	用于自定义指定日期是否禁用。第一个参数为需要判断是否禁用的日期。当处于范围选择过程中且已经选择了一个日期，会作为第二个参数传入。
clearable	boolean	false	已选值是否可以清除。
placeholder	string	range ? datepicker.rangePlaceholder : datepicker.placeholder	未选择时的占位文本。可进行全局配置。
format	`string	function(Date): string=`	'yyyy-MM-dd'/'yyyy-MM'/'yyyy'
parse	function(string): Date=	-	自定义将输入字符串解析为 Date 对象的函数。
shortcuts	Array<Object>	datepicker.shortcuts	[^shortcuts]
expanded	boolean=	false	[^expanded]
disabled	boolean=	false	是否为禁用状态。
readonly	boolean=	false	是否为只读状态。

^^^selected :::badges v-model :::

已选日期（范围）的值，根据 range 属性值的不同，数据格式不同。

+++类型详情

range	类型
false	Date
true	[Date, Date]
+++
^^^

^^^shortcuts 在选择范围时，可以定制的浮层中的快捷选择项列表，格式为 Array<{label, from, to}>。可进行全局配置。

+++字段详情

名称	类型	描述
label	string	快捷选项的文本。
from	开始时间计算方式，见下方快捷选项偏移量数据格式描述。
to	结束时间计算方式，见下方快捷选项偏移量数据格式描述。

+++ ^^^

快捷选项偏移量数据格式

shortcuts 列表项中的 from 及 to 字段格式相同，分别用来设置开始结束日期的计算方式。格式为 number|Object，默认值为 0。

• 类型为 number 时，表示以「今天」为基准，偏移指定天数，比如 -1 等价于 { startOf: 'day', days: -1 }，即「昨天」；

• 类型为 Object 时，支持的格式为：{startOf: string=, days: number=, weeks: number=, months: number=, }。

  +++字段详情

  名称	类型	默认值	描述
  startOf	string=	'day'	起始日期基准，支持的值有 'day'/'week'/'month'/'quarter'/'year'。
  day	number=	-	偏移的天数。
  week	number=	-	偏移的周数。
  month	number=	-	偏移的月数。
  quarter	number=	-	偏移的季度数。
  year	number=	-	偏移的年数。

计算方式是先根据 startOf 设置基准，然后根据其它字段进行偏移量的叠加。

可以根据下面的例子，结合 label 理解计算方式。掌握以后，就可以非常快速地对快捷选项进行设置了。

[
  {
    label: '上个月',
    // 本月第一天往前算一个月，即上月第一天
    from: {
      startOf: 'month',
      month: -1
    },
    // 本月第一天往前算一天，即上月最后一天
    to: {
      startOf: 'month',
      days: -1
    }
  },
  {
    label: '本月',
    // 本月第一天
    from: {
      startOf: 'month'
    },
    // 今天
    to: 0
  },
  {
    label: '本周',
    // 本周第一天，days 为 0 是可以省略的
    from: {
      startOf: 'week',
      days: 0
    },
    // 今天
    to: 0
  },
  {
    label: '最近7天',
    // 往前算 6 天
    from: -6,
    // 到今天
    to: 0
  },
  {
    label: '今天',
    to: 0
  }
]

^^^expanded :::badges .sync :::

下拉浮层是否展开。 ^^^

插槽

名称	描述
date	[^slot-date]

^^^slot-date 浮层中日历的单日单元格内的区域，可用来定制每一天对应区域的内容。

默认内容：对应日期的 date。

+++作用域参数

名称	类型	描述
year	number	完整年份。
month	number	月份数，0 表示一月。
date	number	月份内的日期。
+++
^^^

事件

名称	描述
select	[^event-select]
selectstart	选择日期范围时，选择完起始日期时触发，回调参数 (picking: Date)，表示已选的起始项日期。
selectprogress	[^event-selectprogress]
toggle	下拉浮层展开状态切换时触发，回调参数为 (expanded: boolean)。expanded 表示操作将触发下拉浮层展开还是收起。

^^^event-select :::badges v-model :::

选择修改后触发，回调参数为 (selected)。数据类型和 selected 属性一致。 ^^^

^^^event-selectprogress 选择日期范围时，在已经选择开始日期后，通过鼠标或键盘交互标记到的结束日期变更时触发。回调参数为 (picking)，表示当前标记的日期范围，类型取决于 multiple 属性的值。

+++参数详请

multiple	类型
false	[Date, Date]
true	Array<[Date, Date]>
+++
^^^

全局配置

配置项	类型	默认值	描述
datepicker.shortcuts	Array	[]	快捷选项配置。
datepicker.placeholder	string	@@datepicker.selectDate	选择单日时，未选择状态的占位文本。
datepicker.monthPlaceholder	string	@@datepicker.selectMonth	选择月份时，未选择状态的占位文本。
datepicker.yearPlaceholder	string	@@datepicker.selectYear	选择年时，未选择状态的占位文本。
datepicker.rangePlaceholder	string	@@datepicker.selectRange	选择日期范围时，未选择状态的占位文本。
datepicker.monthRangePlaceholder	string	@@datepicker.selectMonthRange	选择月份范围时，未选择状态的占位文本。
datepicker.yearRangePlaceholder	string	@@datepicker.selectYearRange	选择年份范围时，未选择状态的占位文本。

:::tip @@ 开头的值表示引用多语言配置中的相应字段。 :::

图标

名称	描述
calendar	日历。
clear	清除内容。