Calendar 日历

介绍

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

引入

通过以下方式来全局注册组件,更多注册方式请参考组件注册

  1. import { createApp } from 'vue';
  2. import { Calendar } from 'vant';
  3. const app = createApp();
  4. app.use(Calendar);

代码演示

选择单个日期

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

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

选择多个日期

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

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

选择日期区间

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

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

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

快捷选择

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

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

自定义颜色

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

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

自定义日期范围

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

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

自定义按钮文字

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

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

自定义日期文案

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

  1. <van-calendar v-model:show="show" type="range" :formatter="formatter" />
  1. export default {
  2. setup() {
  3. const 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. return {
  23. formatter,
  24. };
  25. },
  26. };

自定义弹出位置

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

  1. <van-calendar v-model:show="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选择类型:
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是否只渲染可视区域的内容booleantrue
show-mark是否显示月份背景水印booleantrue
show-title是否展示日历标题booleantrue
show-subtitle是否展示日历副标题(年月)booleantrue
show-confirm是否展示确认按钮booleantrue
readonly是否为只读状态,只读状态下不能选择日期booleanfalse
confirm-text确认按钮的文字string确定
confirm-disabled-text确认按钮处于禁用状态时的文字string确定
first-day-of-week设置周起始日0-60

Calendar Poppable Props

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

参数说明类型默认值
v-model:show是否显示日历弹窗booleanfalse
position弹出位置,可选值为 top right leftstringbottom
round是否显示圆角弹窗booleantrue
close-on-popstate是否在页面回退时自动关闭booleantrue
close-on-click-overlay是否在点击遮罩层后关闭booleantrue
safe-area-inset-top是否开启顶部安全区适配booleanfalse
safe-area-inset-bottom是否开启底部安全区适配booleantrue
teleport指定挂载的节点,等同于 Teleport 组件的 to 属性string | Element-

Calendar Range Props

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

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

Calendar Multiple Props

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

参数说明类型默认值
max-range日期最多可选天数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打开弹出层时触发-
close关闭弹出层时触发-
opened打开弹出层且动画结束后触发-
closed关闭弹出层且动画结束后触发-
unselect当日历组件的 typemultiple 时,取消选中日期时触发value: Date
month-show当某个月份进入可视区域时触发{ date: Date, title: string }
over-range范围选择超过最多可选天数时触发-
click-subtitle v3.1.3点击日历副标题时触发event: MouseEvent

Slots

名称说明参数
title自定义标题-
subtitle v3.1.3自定义日历副标题-
footer自定义底部区域内容-
confirm-text v3.2.6自定义确认按钮的内容{ disabled: boolean }
top-info v3.0.17自定义日期上方的提示信息day: Day
bottom-info v3.0.17自定义日期下方的提示信息day: Day

方法

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

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

类型定义

组件导出以下类型定义:

  1. import type {
  2. CalendarType,
  3. CalendarProps,
  4. CalendarDayItem,
  5. CalendarDayType,
  6. CalendarInstance,
  7. } from 'vant';

CalendarInstance 是组件实例的类型,用法如下:

  1. import { ref } from 'vue';
  2. import type { CalendarInstance } from 'vant';
  3. const calendarRef = ref<CalendarInstance>();
  4. calendarRef.value?.reset();

主题定制

样式变量

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

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

常见问题

如何在 formatter 中使用异步返回的数据?

如果需要在 formatter 中使用异步返回的数据,可以使用计算属性动态创建 formatter 函数,示例如下:

  1. const asyncData = ref();
  2. const formatter = computed(() => {
  3. if (!asyncData.value) {
  4. return (day) => day;
  5. }
  6. return (day) => {
  7. day.bottomInfo = asyncData.value;
  8. return day;
  9. };
  10. });
  11. setTimeout(() => {
  12. asyncData.value = '后端文案';
  13. }, 3000);

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

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

对此问题的详细解释:stackoverflow

Calendar 日历 - 图1