TechUI Docs

简中

EN

简中

EN

主题

日历 ​

TuiCalendar 是一个可视化的日历组件。 底层基于 Day.js 进行日期计算，支持月视图导航、待办事项标记、自定义日期单元格内容，非常适合用于日程管理、考勤展示或任务看板。

基础用法 ​

默认展示 ​

绑定 v-model 即可显示日历。默认以星期日为一周的开始。

html
<script setup>
import { ref } from 'vue';

const value = ref(new Date());
</script>

<template>
  <TuiCalendar v-model="value" />
</template>

数据集成 ​

待办事项 (Todos) ​

通过 todos 属性传入一个对象，键为日期字符串（格式需匹配 Day.js 解析，推荐 YYYY-MM-DD），值为待办数量。 组件会自动在对应日期显示徽标（Tag）。

  • tagConfig: 可传入 TuiTag 的配置对象（如 { round: true, type: 'danger' }）来统一控制标记样式。
html
<script setup>
import { ref } from 'vue';

const value = ref(new Date());
const todoData = ref({
  '2025-06-06': 3,
  '2025-06-07': 5,
  '2025-06-15': 1
});
</script>

<template>
  <TuiCalendar 
    v-model="value" 
    :todos="todoData" 
    :tagConfig="{ round: true }"
  />
</template>

高级定制 ​

自定义单元格内容 (Slot) ​

使用 #date-cell="{ data }" 插槽可以完全自定义日期格子的渲染内容。 data 参数包含：

  • date: Date 对象。
  • day: 当前日期的天数（如 '01', '15'）。
  • todoCount: 对应 todos 中的数量。
  • isSelected: 是否当前选中。
  • type: 日期类型 ('prev-month', 'current-month', 'next-month')。
html
<template>
  <TuiCalendar v-model="value" :todos="todoData">
    <template #date-cell="{ data }">
      <div class="custom-cell" :class="{ 'is-selected': data.isSelected }">
        <span class="day-num">{{ data.day }}</span>
        
        <div v-if="data.todoCount > 0" class="todo-info">
          <i class="tui-icon ti-bell"></i>
          <span>{{ data.todoCount }} 待办</span>
        </div>
      </div>
    </template>
  </TuiCalendar>
</template>

<style scoped>
.custom-cell { height: 100%; padding: 8px; }
.todo-info { font-size: 12px; color: #f56c6c; margin-top: 4px; }
</style>

布局与格式 ​

  • weekStartsOn: 设置 'monday' 可让周一作为一周的起始。
  • titleAlign: 标题栏（年月显示）对齐方式 (left, center, right)。
  • cellAlign: 单元格内容对齐方式。
  • buttons: 控制右上角显示的按钮组，默认 ['year', 'month', 'today']。
html
<TuiCalendar
  weekStartsOn="monday"
  titleAlign="center"
  cellAlign="center"
  :buttons="['month', 'today']"
  buttonSize="small"
/>

API 参考 ​

Props ​

属性名类型默认值说明
modelValueDate/Stringnew Date()绑定值。
todosObject{}待办事项数据映射 { 'YYYY-MM-DD': number }。
rangeArray[]时间范围，包括开始时间与结束时间。[startDate, endDate]
weekStartsOnString'sunday'一周的开始日。可选：sunday, monday。
weekdayFormatString'weekdayShort'星期栏显示格式。可选：weekday, weekdayShort, weekdayMin。
buttonsArray['year', 'month', 'today']头部操作栏显示的按钮。
buttonSizeString'default'按钮尺寸。
titleAlignString'left'头部标题对齐方式。可选：left, center, right。
cellAlignString'left'日期单元格内容对齐方式。
tagConfigObject-待办标记 Tag 的配置对象。

Events ​

事件名说明回调参数
update:modelValue绑定值变化时触发。(value: Date)
change选中日期改变时触发。(value: Date)
select点击日期单元格时触发。(value: Date)

Slots ​

插槽名说明参数
date-cell自定义日期单元格内容。{ data: { date, day, type, isSelected, todoCount } }

Exposed Methods ​

方法名说明参数
selectDate选中某一天。`(type: 'prev-month'
pickDay选中具体日期。(day: Dayjs)
currentDateDayjsComputed。当前面板显示的月份（Dayjs 对象）。-
selectedDateDayjsComputed。当前选中的日期（Dayjs 对象）。-