Calendar 日历

介绍

日历组件用于选择日期或日期区间,2.4 版本开始支持此组件。

引入

  1. import Vue from 'vue';
  2. import { Calendar } from 'vant';
  3. Vue.use(Calendar);

代码演示

选择单个日期

下面演示了结合单元格来使用日历组件的用法,日期选择完成后会触发 confirm 事件。

  1. <van-cell title="选择单个日期" :value="date" @click="show = true" />
  2. <van-calendar v-model="show" @confirm="onConfirm" />
  1. export default {
  2. data() {
  3. return {
  4. date: '',
  5. show: false,
  6. };
  7. },
  8. methods: {
  9. formatDate(date) {
  10. return `${date.getMonth() + 1}/${date.getDate()}`;
  11. },
  12. onConfirm(date) {
  13. this.show = false;
  14. this.date = this.formatDate(date);
  15. },
  16. },
  17. };

选择多个日期

设置 typemultiple 后可以选择多个日期,此时 confirm 事件返回的 date 为数组结构,数组包含若干个选中的日期。

  1. <van-cell title="选择多个日期" :value="text" @click="show = true" />
  2. <van-calendar v-model="show" type="multiple" @confirm="onConfirm" />
  1. export default {
  2. data() {
  3. return {
  4. text: '',
  5. show: false,
  6. };
  7. },
  8. methods: {
  9. onConfirm(date) {
  10. this.show = false;
  11. this.text = `选择了 ${date.length} 个日期`;
  12. },
  13. },
  14. };

选择日期区间

设置 typerange 后可以选择日期区间,此时 confirm 事件返回的 date 为数组结构,数组第一项为开始时间,第二项为结束时间。

  1. <van-cell title="选择日期区间" :value="date" @click="show = true" />
  2. <van-calendar v-model="show" type="range" @confirm="onConfirm" />
  1. export default {
  2. data() {
  3. return {
  4. date: '',
  5. show: false,
  6. };
  7. },
  8. methods: {
  9. formatDate(date) {
  10. return `${date.getMonth() + 1}/${date.getDate()}`;
  11. },
  12. onConfirm(date) {
  13. const [start, end] = date;
  14. this.show = false;
  15. this.date = `${this.formatDate(start)} - ${this.formatDate(end)}`;
  16. },
  17. },
  18. };

Tips: 默认情况下,日期区间的起止时间不能为同一天,可以通过设置 allow-same-day 属性来允许选择同一天。

快捷选择

show-confirm 设置为 false 可以隐藏确认按钮,这种情况下选择完成后会立即触发 confirm 事件。

  1. <van-calendar v-model="show" :show-confirm="false" />

自定义颜色

通过 color 属性可以自定义日历的颜色,对选中日期和底部按钮生效。

  1. <van-calendar v-model="show" color="#1989fa" />

自定义日期范围

通过 min-datemax-date 定义日历的范围。

  1. <van-calendar v-model="show" :min-date="minDate" :max-date="maxDate" />
  1. export default {
  2. data() {
  3. return {
  4. show: false,
  5. minDate: new Date(2010, 0, 1),
  6. maxDate: new Date(2010, 0, 31),
  7. };
  8. },
  9. };

自定义按钮文字

通过 confirm-text 设置按钮文字,通过 confirm-disabled-text 设置按钮禁用时的文字。

  1. <van-calendar
  2. v-model="show"
  3. type="range"
  4. confirm-text="完成"
  5. confirm-disabled-text="请选择结束时间"
  6. />

自定义日期文案

通过传入 formatter 函数来对日历上每一格的内容进行格式化。

  1. <van-calendar v-model="show" type="range" :formatter="formatter" />
  1. export default {
  2. methods: {
  3. formatter(day) {
  4. const month = day.date.getMonth() + 1;
  5. const date = day.date.getDate();
  6. if (month === 5) {
  7. if (date === 1) {
  8. day.topInfo = '劳动节';
  9. } else if (date === 4) {
  10. day.topInfo = '青年节';
  11. } else if (date === 11) {
  12. day.text = '今天';
  13. }
  14. }
  15. if (day.type === 'start') {
  16. day.bottomInfo = '入住';
  17. } else if (day.type === 'end') {
  18. day.bottomInfo = '离店';
  19. }
  20. return day;
  21. },
  22. },
  23. };

自定义弹出位置

通过 position 属性自定义弹出层的弹出位置,可选值为 topleftright

  1. <van-calendar v-model="show" :round="false" position="right" />

日期区间最大范围

选择日期区间时,可以通过 max-range 属性来指定最多可选天数,选择的范围超过最多可选天数时,会弹出相应的提示文案。

  1. <van-calendar type="range" :max-range="3" :style="{ height: '500px' }" />

自定义周起始日

通过 first-day-of-week 属性设置一周从哪天开始。

  1. <van-calendar first-day-of-week="1" />

平铺展示

poppable 设置为 false,日历会直接展示在页面内,而不是以弹层的形式出现。

  1. <van-calendar
  2. title="日历"
  3. :poppable="false"
  4. :show-confirm="false"
  5. :style="{ height: '500px' }"
  6. />

API

Props

参数说明类型默认值
type v2.5.4选择类型:
single表示选择单个日期,
multiple表示选择多个日期,
range表示选择日期区间
stringsingle
title日历标题string日期选择
color主题色,对底部按钮和选中日期生效string#ee0a24
min-date可选择的最小日期Date当前日期
max-date可选择的最大日期Date当前日期的六个月后
default-date默认选中的日期,typemultiplerange 时为数组,传入 null 表示默认不选择Date | Date[] | null今天
row-height日期行高number | string64
formatter日期格式化函数(day: Day) => Day-
poppable是否以弹层的形式展示日历booleantrue
lazy-render v2.8.1是否只渲染可视区域的内容booleantrue
show-mark是否显示月份背景水印booleantrue
show-title v2.5.5是否展示日历标题booleantrue
show-subtitle v2.5.5是否展示日历副标题(年月)booleantrue
show-confirm是否展示确认按钮booleantrue
readonly v2.10.5是否为只读状态,只读状态下不能选择日期booleanfalse
confirm-text确认按钮的文字string确定
confirm-disabled-text确认按钮处于禁用状态时的文字string确定
first-day-of-week v2.9.2设置周起始日0-60

Poppable Props

当 Canlendar 的 poppabletrue 时,支持以下 props:

参数说明类型默认值
v-model是否显示日历弹窗booleanfalse
position弹出位置,可选值为 top right leftstringbottom
round是否显示圆角弹窗booleantrue
close-on-popstate是否在页面回退时自动关闭booleantrue
close-on-click-overlay是否在点击遮罩层后关闭booleantrue
safe-area-inset-bottom是否开启底部安全区适配booleantrue
get-container指定挂载的节点,用法示例string | () => Element-

Range Props

当 Canlendar 的 typerange 时,支持以下 props:

参数说明类型默认值
max-range日期区间最多可选天数number | string无限制
range-prompt范围选择超过最多可选天数时的提示文案string选择天数不能超过 xx 天
allow-same-day v2.5.6是否允许日期范围的起止时间为同一天booleanfalse

Multiple Props

当 Canlendar 的 typemultiple 时,支持以下 props:

参数说明类型默认值
max-range v2.7.2日期最多可选天数number | string无限制
range-prompt选择超过最多可选天数时的提示文案string选择天数不能超过 xx 天

Day 数据结构

日历中的每个日期都对应一个 Day 对象,通过formatter属性可以自定义 Day 对象的内容

键名说明类型
date日期对应的 Date 对象Date
type日期类型,可选值为selectedstartmiddleenddisabledstring
text中间显示的文字string
topInfo上方的提示信息string
bottomInfo下方的提示信息string
className额外类名string

Events

事件名说明回调参数
select点击并选中任意日期时触发value: Date | Date[]
confirm日期选择完成后触发,若show-confirmtrue,则点击确认按钮后触发value: Date | Date[]
open v2.5.2打开弹出层时触发-
close v2.5.2关闭弹出层时触发-
opened v2.5.2打开弹出层且动画结束后触发-
closed v2.5.2关闭弹出层且动画结束后触发-
unselect v2.7.2当日历组件的 typemultiple 时,取消选中日期时触发value: Date
month-show v2.8.2当某个月份进入可视区域时触发{ date: Date, title: string }

Slots

名称说明
title自定义标题
footer自定义底部区域内容

方法

通过 ref 可以获取到 Calendar 实例并调用实例方法,详见组件实例方法

方法名说明参数返回值
reset将选中的日期重置到指定日期,未传参时会重置到默认日期date?: Date | Date[]-
scrollToDate v2.12.2滚动到某个日期date: Date-

样式变量

组件提供了下列 Less 变量,可用于自定义样式,使用方法请参考主题定制

名称默认值描述
@calendar-background-color@white-
@calendar-popup-height80%-
@calendar-header-box-shadow0 2px 10px rgba(125, 126, 128, 0.16)-
@calendar-header-title-height44px-
@calendar-header-title-font-size@font-size-lg-
@calendar-header-subtitle-font-size@font-size-md-
@calendar-weekdays-height30px-
@calendar-weekdays-font-size@font-size-sm-
@calendar-month-title-font-size@font-size-md-
@calendar-month-mark-colorfade(@gray-2, 80%)-
@calendar-month-mark-font-size160px-
@calendar-day-height64px-
@calendar-day-font-size@font-size-lg-
@calendar-range-edge-color@white-
@calendar-range-edge-background-color@red-
@calendar-range-middle-color@red-
@calendar-range-middle-background-opacity0.1-
@calendar-selected-day-size54px-
@calendar-selected-day-color@white-
@calendar-info-font-size@font-size-xs-
@calendar-info-line-height@line-height-xs-
@calendar-selected-day-background-color@red-
@calendar-day-disabled-color@gray-5-
@calendar-confirm-button-height36px-
@calendar-confirm-button-margin7px 0-

常见问题

在 iOS 系统上初始化组件失败?

如果你遇到了在 iOS 上无法渲染组件的问题,请确认在创建 Date 对象时没有使用new Date('2020-01-01')这样的写法,iOS 不支持以中划线分隔的日期格式,正确写法是new Date('2020/01/01')

对此问题的详细解释:stackoverflow

Calendar 日历 - 图1