Calendar 日历

介绍

用于日历展示、选择日期或日期区间。

基础用法

通过 v-model 绑定选中的日期/年份，通过 type 设置日历的选择类型，支持设置 date month year 类型的日历。

<!-- 日期选择 -->
<vd-calendar v-model="date" />
<!-- 月份选择 -->
<vd-calendar v-model="month" type="month" />
<!-- 年份选择 -->
<vd-calendar v-model="year" type="year" />

const date = ref('2025-01-01');
const month = ref('2025-01');
const year = ref('2025');

展示重置按钮

通过 resetable 属性展示重置按钮，设置后会改变日历顶部操作布局，点击重置按钮后会回到当前选中值，未选中时回到 今天。

<vd-calendar v-model="date" resetable />

const date = ref('2025-01-01');

设置选择类型

通过 select-type 属性设置选择类型，支持 single multiple range week 类型选择方式。

<!-- 单选 -->
<vd-calendar v-model="single" />
<!-- 多选 -->
<vd-calendar v-model="multiple" select-type="multiple" />
<!-- 范围选择 -->
<vd-calendar v-model="range" select-type="range" />
<!-- 星期选择 -->
<vd-calendar v-model="week" select-type="week" />

const single = ref('2025-01-01');
const multiple = ref([
  '2025-01-01',
  '2025-02-01',
  '2025-03-01',
]);
const range = ref(['2025-05-01', '2025-06-01']);
const week = ref(['2025-05-11', '2025-05-17']);

自定义周起始日

通过 week-first 属性设置周起始日，通过 0~6 数值来设置（周日为 0，周一至周六为 1-6），设置后会影响 week 选择类型的起始日期。

<vd-calendar
  v-model="week"
  select-type="week"
  week-first="1"
/>

const week = ref([]);

自定义描述类型

通过 desc-type 属性设置描述类型，支持 festival term lunar 三种类型，可设置多个，按数组排序来决定显示的优先级。

<vd-calendar
  v-model="date"
  :desc-type="descType"
/>

import { CalendarDateDescType } from 'vital-design';

const descType: CalendarDateDescType[] = [
  'festival', // 节日
  'term', // 节气
  'lunar', // 农历
];

const date = ref('');

日期限制

通过 min 和 max 属性设置最大、最小日期限制，支持 dayjs 日期。

<vd-calendar
  v-model="date"
  :min="limit.min"
  :max="limit.max"
/>

import dayjs from 'dayjs';

const date = ref('');

// 字符日期
const limit = reactive({
  min: '2025-01-01',
  max: '2026-01-01',
});

// dayjs日期
const limit2 = reactive({
  min: dayjs().subtract(1, 'month'),
  max: dayjs().add(1 ,'month'),
});

单独使用视图

可根据需求单独使用日期、月份、年份选择器。

<!-- 日期视图 -->
<vd-calendar-date v-model="date" :show-mark="true" />
<!-- 月份视图 -->
<vd-calendar-month v-model="month" :show-mark="true" />
<!-- 年份视图 -->
<vd-calendar-year v-model="year" />

const date = ref('2025-01-01');
const month = ref('2025-01');
const year = ref('2025');

API

Calendar Props

参数	说明	类型	默认值
v-model	选中日期	string | number | Date | (string | number | Date)[]	-
active	激活日期	string | number | Date	今天
type	日历类型	CalendarType	date
select-type	选择类型	CalendarSelectType	single
min	最小日期	string | number | Date | dayjs.Dayjs	十年前
max	最大日期	string | number | Date | dayjs.Dayjs	十年后
week-first	周起始日	number	以 dayjs 为准
desc-type	描述类型	CalendarDateDescType[]	[]
show-mark	是否显示背景水印	boolean	false
allow-same	区间选择时，是否允许开始日期等于结束日期	boolean	true
resetable	是否展示重置按钮	boolean	false
switchable	是否允许点击标题切换日历类型	boolean	true
swipeable	是否开启左右滑动手势切换	boolean	true
cell-class	格子类名格式化方法	CalendarCellClass	-
cell-text	格子文字格式化方法	CalendarCellText	-
cell-desc	格子描述格式化方法	CalendarCellText	-

CalendarDate Props

参数	说明	类型	默认值
v-model	选中日期	string | number | Date | (string | number | Date)[]	-
active	激活月份	string | number | Date	今天
select-type	选择类型	CalendarSelectType	single
min-date	最小日期	string | number | Date | dayjs.Dayjs	十年前
max-date	最大日期	string | number | Date | dayjs.Dayjs	十年后
week-first	周起始日	number	以 dayjs 为准
desc-type	描述类型	CalendarDateDescType[]	[]
show-mark	是否显示背景水印	boolean	false
allow-same	区间选择时，是否允许开始日期等于结束日期	boolean	true
cell-class	格子类名格式化方法	CalendarCellClass	-
cell-text	格子文字格式化方法	CalendarCellText	-
cell-desc	格子描述格式化方法	CalendarCellText	-

CalendarMonth Props

参数	说明	类型	默认值
v-model	选中月份	string | number | Date | (string | number | Date)[]	-
active	激活年份	string | number	今年
select-type	选择类型	CalendarSelectType	single
min-month	最小月份日期	string | number | Date | dayjs.Dayjs	十年前
max-month	最大月份日期	string | number | Date | dayjs.Dayjs	十年后
show-mark	是否显示背景水印	boolean	false
allow-same	区间选择时，是否允许开始日期等于结束日期	boolean	true
cell-class	格子类名格式化方法	CalendarCellClass	-
cell-text	格子文字格式化方法	CalendarCellText	-
cell-desc	格子描述格式化方法	CalendarCellText	-

CalendarYear Props

参数	说明	类型	默认值
v-model	选中月份	string | number | (string | number)[]	-
active	激活年份	string | number	今年
select-type	选择类型	CalendarSelectType	single
min-year	最小年份	string | number	十年前
max-year	最大年份	string | number	十年后
allow-same	区间选择时，是否允许开始日期等于结束日期	boolean	true
cell-class	格子类名格式化方法	CalendarCellClass	-
cell-text	格子文字格式化方法	CalendarCellText	-
cell-desc	格子描述格式化方法	CalendarCellText	-

代替原始 Props

参数	说明	类型	默认值
custom-id	根节点id	string	-
custom-class	根节点类名	ClassValue	-
custom-style	根节点样式	StyleValue	-

Events

事件名	说明	回调参数
click	点击时触发	MouseEvent
click-date	点击日期时触发	CalendarDateItem
click-month	点击月份时触发	CalendarMonthItem
click-year	点击年份时触发	CalendarYearItem

Slots

名称	说明
title	标题
prev	上一个按钮
next	下一个按钮
reset	重置按钮