Vant4 Calendar 日历

介绍

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

引入

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

import { createApp } from vue;
import { Calendar } from vant;

const app = createApp();
app.use(Calendar);

代码演示

选择单个日期

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

<van-cell title="选择单个日期" :value="date" @click="show = true" />
<van-calendar v-model:show="show" @confirm="onConfirm" />

import { ref } from vue;

export default {
  setup() {
    const date = ref();
    const show = ref(false);

    const formatDate = (date) => `${date.getMonth() + 1}/${date.getDate()}`;
    const onConfirm = (value) => {
      show.value = false;
      date.value = formatDate(value);
    };

    return {
      date,
      show,
      onConfirm,
    };
  },
};

选择多个日期

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

<van-cell title="选择多个日期" :value="text" @click="show = true" />
<van-calendar v-model:show="show" type="multiple" @confirm="onConfirm" />

import { ref } from vue;

export default {
  setup() {
    const text = ref();
    const show = ref(false);

    const onConfirm = (dates) => {
      show.value = false;
      text.value = `选择了 ${dates.length} 个日期`;
    };

    return {
      text,
      show,
      onConfirm,
    };
  },
};

选择日期区间

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

<van-cell title="选择日期区间" :value="date" @click="show = true" />
<van-calendar v-model:show="show" type="range" @confirm="onConfirm" />

import { ref } from vue;

export default {
  setup() {
    const date = ref();
    const show = ref(false);

    const formatDate = (date) => `${date.getMonth() + 1}/${date.getDate()}`;
    const onConfirm = (values) => {
      const [start, end] = values;
      show.value = false;
      date.value = `${formatDate(start)} - ${formatDate(end)}`;
    };

    return {
      date,
      show,
      onConfirm,
    };
  },
};

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

快捷选择

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

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

自定义颜色

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

<van-calendar v-model:show="show" color="#ee0a24" />

自定义日期范围

通过 ​min-date​ 和 ​max-date​ 定义日历的范围。

<van-calendar v-model:show="show" :min-date="minDate" :max-date="maxDate" />

import { ref } from vue;

export default {
  setup() {
    const show = ref(false);

    return {
      show,
      minDate: new Date(2010, 0, 1),
      maxDate: new Date(2010, 0, 31),
    };
  },
};

自定义按钮文字

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

<van-calendar
  v-model:show="show"
  type="range"
  confirm-text="完成"
  confirm-disabled-text="请选择结束时间"
/>

自定义日期文案

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

<van-calendar v-model:show="show" type="range" :formatter="formatter" />

export default {
  setup() {
    const 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;
    };

    return {
      formatter,
    };
  },
};

自定义弹出位置

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

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

日期区间最大范围

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

<van-calendar type="range" :max-range="3" :style="" />

自定义周起始日

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

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

平铺展示

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

<van-calendar
  title="日历"
  :poppable="false"
  :show-confirm="false"
  :style=""
/>

API

Props

Calendar Poppable Props

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

Calendar Range Props

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

Calendar Multiple Props

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

Day 数据结构

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

Events

Slots

方法

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

类型定义

组件导出以下类型定义：

import type {
  CalendarType,
  CalendarProps,
  CalendarDayItem,
  CalendarDayType,
  CalendarInstance,
} from vant;

​CalendarInstance​ 是组件实例的类型，用法如下：

import { ref } from vue;
import type { CalendarInstance } from vant;

const calendarRef = ref<CalendarInstance>();

calendarRef.value?.reset();

主题定制

样式变量

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

常见问题

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

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

const asyncData = ref();

const formatter = computed(() => {
  if (!asyncData.value) {
    return (day) => day;
  }
  return (day) => {
    day.bottomInfo = asyncData.value;
    return day;
  };
});

setTimeout(() => {
  asyncData.value = 后端文案;
}, 3000);

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

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

对此问题的详细解释：stackoverflow。