ContextQMD
Back to Vant Weapp

Calendar 日历

packages/calendar/README.md

1.11.710.2 KB
Original Source

Calendar 日历

介绍

日历组件用于选择日期或日期区间。

引入

在app.json或index.json中引入组件，详细介绍见快速上手。

json
"usingComponents": {
  "van-calendar": "@vant/weapp/calendar/index"
}

代码演示

选择单个日期

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

html
<van-cell title="选择单个日期" value="{{ date }}" bind:click="onDisplay" />
<van-calendar show="{{ show }}" bind:close="onClose" bind:confirm="onConfirm" />
js
Page({
  data: {
    date: '',
    show: false,
  },

  onDisplay() {
    this.setData({ show: true });
  },
  onClose() {
    this.setData({ show: false });
  },
  formatDate(date) {
    date = new Date(date);
    return `${date.getMonth() + 1}/${date.getDate()}`;
  },
  onConfirm(event) {
    this.setData({
      show: false,
      date: this.formatDate(event.detail),
    });
  },
});

选择多个日期

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

html
<van-cell title="选择多个日期" value="{{ text }}" bind:click="onDisplay" />
<van-calendar
  show="{{ show }}"
  type="multiple"
  bind:close="onClose"
  bind:confirm="onConfirm"
/>
js
Page({
  data: {
    text: '',
    show: false,
  },

  onDisplay() {
    this.setData({ show: true });
  },
  onClose() {
    this.setData({ show: false });
  },
  onConfirm(event) {
    this.setData({
      show: false,
      text: `选择了 ${event.detail.length} 个日期`,
    });
  },
});

选择日期区间

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

html
<van-cell title="选择日期区间" value="{{ date }}" bind:click="onDisplay" />
<van-calendar
  show="{{ show }}"
  type="range"
  bind:close="onClose"
  bind:confirm="onConfirm"
/>
js
Page({
  data: {
    date: '',
    show: false,
  },

  onDisplay() {
    this.setData({ show: true });
  },
  onClose() {
    this.setData({ show: false });
  },
  formatDate(date) {
    date = new Date(date);
    return `${date.getMonth() + 1}/${date.getDate()}`;
  },
  onConfirm(event) {
    const [start, end] = event.detail;
    this.setData({
      show: false,
      date: `${this.formatDate(start)} - ${this.formatDate(end)}`,
    });
  },
});

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

快捷选择

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

html
<van-calendar show="{{ show }}" show-confirm="{{ false }}" />

自定义颜色

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

html
<van-calendar show="{{ show }}" color="#07c160" />

自定义日期范围

通过min-date和max-date定义日历的范围，需要注意的是min-date和max-date的区间不宜过大，否则会造成严重的性能问题。

html
<van-calendar
  show="{{ show }}"
  min-date="{{ minDate }}"
  max-date="{{ maxDate }}"
/>
js
Page({
  data: {
    show: false,
    minDate: new Date(2010, 0, 1).getTime(),
    maxDate: new Date(2010, 0, 31).getTime(),
  },
});

自定义按钮文字

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

html
<van-calendar
  show="{{ show }}"
  type="range"
  confirm-text="完成"
  confirm-disabled-text="请选择结束时间"
/>

自定义日期文案

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

html
<van-calendar show="{{ show }}" type="range" formatter="{{ formatter }}" />
js
Page({
  data: {
    formatter(day) {
      const month = day.date.getMonth() + 1;
      const date = day.date.getDate();

      if (month === 5) {
        if (date === 1) {
          day.topInfo = '劳动节';
        } else if (date === 4) {
          day.topInfo = '五四青年节';
        } else if (date === 11) {
          day.text = '今天';
        }
      }

      if (day.type === 'start') {
        day.bottomInfo = '入住';
      } else if (day.type === 'end') {
        day.bottomInfo = '离店';
      }

      return day;
    },
  },
});

自定义弹出位置

通过position属性自定义弹出层的弹出位置，可选值为top、left、right。

html
<van-calendar show="{{ show }}" round="false" position="right" />

日期区间最大范围

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

html
<van-calendar type="range" max-range="{{ 3 }}" />

自定义周起始日

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

html
<van-calendar first-day-of-week="{{ 1 }}" />

平铺展示

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

html
<van-calendar
  title="日历"
  poppable="{{ false }}"
  show-confirm="{{ false }}"
  class="calendar"
/>
css
.calendar {
  --calendar-height: 618px;
}

Tips: 注意，在自定义calendar的高度时，需要确保，滚动到当前月份时，所有的日期要展现在.van-calendar__body内，否则可能会出现滚动时头部月份与当前月份不同步的情况。目前平铺型预设高度618px,弹窗型高度90%。

API

Props

参数说明类型默认值
type选择类型:
single表示选择单个日期，
multiple表示选择多个日期，
range表示选择日期区间stringsingle
title日历标题string日期选择
color主题色，对底部按钮和选中日期生效string#ee0a24
min-date可选择的最小日期timestamp当前日期
max-date可选择的最大日期timestamp当前日期的六个月后
default-date v1.10.21默认选中的日期，type为multiple或range时为数组，传入 null 表示默认不选择timestamp | timestamp[] | null今天
row-height日期行高number | string64
formatter日期格式化函数(day: Day) => Day-
poppable是否以弹层的形式展示日历booleantrue
show-mark是否显示月份背景水印booleantrue
show-title是否展示日历标题booleantrue
show-subtitle是否展示日历副标题（年月）booleantrue
show-confirm是否展示确认按钮booleantrue
confirm-text确认按钮的文字string确定
confirm-disabled-text确认按钮处于禁用状态时的文字string确定
first-day-of-week设置周起始日0~60
readonly v1.9.1是否为只读状态，只读状态下不能选择日期booleanfalse
root-portal v1.11.3是否从页面子树中脱离出来，用于解决各种 fixed 失效问题，微信基础库 >= 2.25.2 booleanfalse

Poppable Props

当 Calendar 的 poppable 为 true 时，支持以下 props:

参数说明类型默认值
show是否显示日历弹窗booleanfalse
position弹出位置，可选值为 top right leftstringbottom
round是否显示圆角弹窗booleantrue
close-on-click-overlay是否在点击遮罩层后关闭booleantrue
safe-area-inset-bottom是否开启底部安全区适配booleantrue

Range Props

当 Calendar 的 type 为 range 时，支持以下 props:

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

Multiple Props

当 Calendar 的 type 为 multiple 时，支持以下 props:

参数说明类型默认值
min-range日期最少可选天数number | string1

Day 数据结构

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

键名说明类型
date日期对应的 Date 对象Date
type日期类型，可选值为selected、start、middle、end、disabledstring
text中间显示的文字string
topInfo上方的提示信息string
bottomInfo下方的提示信息string
className自定义 classNamestring

Events

事件名说明回调参数
bind:select点击任意日期时触发value: Date | Date[]
bind:unselect当 Calendar 的 type 为 multiple 时,点击已选中的日期时触发value: Date
bind:confirm日期选择完成后触发，若show-confirm为true，则点击确认按钮后触发value: Date | Date[]
bind:open打开弹出层时触发-
bind:close关闭弹出层时触发-
bind:opened打开弹出层且动画结束后触发-
bind:closed关闭弹出层且动画结束后触发-
bind:over-range范围选择超过最多可选天数时触发-
bind:click-subtitle v1.8.1点击日历副标题时触发WechatMiniprogram.TouchEvent

Slots

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

方法

通过 selectComponent 可以获取到 Calendar 实例并调用实例方法。

方法名说明参数返回值
reset重置选中的日期到默认值--