Calendar 日历

介绍

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

选择单个日期

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

<z-cell title="选择单个日期" :value="date" @click="show = true" />
<z-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 为数组结构，数组包含若干个选中的日期。

<z-cell title="选择多个日期" :value="text" @click="show = true" />
<z-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 为数组结构，数组第一项为开始时间，第二项为结束时间。

<z-cell title="选择日期区间" :value="date" @click="show = true" />
<z-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 事件。

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

自定义颜色

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

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

自定义日期范围

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

<z-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 设置按钮禁用时的文字。

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

自定义日期文案

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

<z-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。

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

日期区间最大范围

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

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

自定义周起始日

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

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

平铺展示

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

<z-calendar
  title="日历"
  :poppable="false"
  :show-confirm="false"
  :custom-style="{ height: '500px' }"
/>

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 实例并调用实例方法。

样式变量

组件提供了下列 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);