TUI

TsCalendar 日历组件
支持基础渲染、自定义节假日、调休日、高亮选中等功能的日历展示组件。
基础用法
展示一个最简单的日历组件。
2025年
12月
回到今天
示例代码
vue
<template>
  <TsCalendar />
</template>
默认选中与阴影
设置 defaultActiveDay 选中某一天,并开启 shadow 阴影。
2025年
12月
回到今天
示例代码
vue
<template>
  <TsCalendar defaultActiveDay="7" shadow />
</template>
显示月份详情
通过 change、 onMonthChange 获取月份详情数据来打造自己的个性化月份数据展示。
2025年
12月
回到今天
本月假期天数 天
本月工作天数 天
示例代码
vue
<template>
  <TsCalendar @change="handleChange" @onMonthChange="onMonthChange" />
  <BussinessCalendarMonthDetail :data="currentDayData" :monthDetail="currentMonthDetail" />
</template>

<script setup lang="ts">
  interface CalendarMonthCount {
    restDayCount: number;
    workDayCount: number;
  }
  const currentMonthDetail = ref({}) as Ref<CalendarMonthCount>;
  const currentDayData = ref({}) as Ref<CalendarDay>;

  const handleChange = (data: CalendarDay) => {
    currentDayData.value = data;
  };

  const onMonthChange = ({ monthDays }: MonthChangePayload) => {
    const restDayCount = monthDays.reduce((acc, item) => {
      const isWeekend = [6, 7].includes(item.week);
      let value = 0;
      if (item.type === CalendarStatusEnum.Holiday) value = isWeekend ? 0 : 1;
      if (item.type === CalendarStatusEnum.Weekend) value = 1;
      if (item.type === CalendarStatusEnum.Workday && isWeekend) value = -1;
      return acc + value;
    }, 0);

    currentMonthDetail.value = {
      restDayCount,
      workDayCount: monthDays.length - restDayCount,
    };
  };
</script>
开启悬浮提示
通过 showTooltip 开启 hover 悬浮提示内容。或者 CalendarDay enableTip 字段精细到每一天开启。
2025年
12月
回到今天
示例代码
vue
<template>
  <TsCalendar :showTooltip="true">
    <template #tooltip>
      <div class="calendar-tip-content">showTooltip 会显示每一天自定义悬浮提示内容,可以是任何内容,包括 HTML。</div>
    </template>
  </TsCalendar>
</template>
自定义节假日

通过 extensions 传入自定义节假日数据,渲染名称、状态等信息。

以2025年1月1日 节假日数据作为展示

2025年
12月
回到今天
示例代码
vue
<template>
  <TsCalendar :extensions="holidayData" />
</template>
<script setup lang="ts">
  const holidayData: CalendarOriginMap = {
      '2025': {
        '11': [
          {
            id: 1,
            date: '2025-11-01',
            name: '测试假日',
            type: 'holiday',
            badgeText: '休',
            tooltip: true,
            tooltipText: '这是一个用来展示的假日',
          },
        ],
      }
  };
</script>
属性 Props
属性名
说明
类型
可选值
默认值
版本说明
defaultActiveDay
当前选中日期
String | Date | null
null
extensions
年假数据
ExternalCalendarMap
{}
deprecated 0.3.9
extensions
年假数据
CalendarExtensions
{}
added 0.3.9
showTooltip
是否显示提示
Boolean
true / false
false
tooltipOffset
提示偏移量
[number, number]
-
[0, 5]
shadow
是否显示阴影边框
Boolean | String | Null
true / "" / null
false
事件 Events
事件名
说明
回调参数
版本说明
change
选中日期
(value: CalendarDay, isInit: boolean) => void
onMonthChange
选中日期
(value: MonthChangePayload) => void
插槽 Slots
插槽名
说明
版本说明
tooltip
自定义 tooltip 内容
CalendarExtensions props
属性名
说明
类型
格式
可选值
默认值
year
年份
string
YYYY
[year: string]: { [month in Month]?: ExternalDay[]; }
CalendarDay props
属性名
说明
类型
格式
可选值
默认值
date
年份,例如2025-10-05
string
YYYY-MM-DD
-
name
显示名称,例如“国庆节”
string
-
type
控制样式/标签
CalendarStatus
normal / holiday / workday / weekend
badgeText
右上角标签
string
-
tooltip
是否显示悬浮提示
boolean
-
tooltipText
悬浮提示
string
-
lunarName
农历名称
string
-
CalendarDay extends ExternalDay props
属性名
说明
类型
格式
可选值
默认值
year
年份
string
YYYY
-
month
月份
string
MM
-
day
日期
number
DD
-
week
星期
Number
1~7
nameCn
中文名称
string
-
yearCn
中文年份日期
string
-
monthCn
中文月份日期
string
-
dayCn
中文日期
string
-
animal
生肖
string
-
term
节气
boolean
-
MonthChangePayload props
属性名
说明
类型
格式
可选值
默认值
year
年份
string
YYYY
-
month
月份
string
MM
-
monthDays
当前月所有日期(已经合并外部标记)
CalendarDay[]
-