Calendar 日历

按照日历形式展示数据的容器。

何时使用

当需要按日历形式展示一组数据，或让用户选择日期时使用。

基础用法

使用 v-model 实现日期选择，默认周一作为每周起始日。

<TCalendar v-model="selectedDate" />

受控模式

传入预设值，日历自动高亮对应日期。

const presetDate = ref('2026-06-01')
<TCalendar v-model="presetDate" />

显示周序号

设置 show-week 属性在左侧显示 ISO 周序号列。

<TCalendar show-week />

自动切换月

点击上个月或下个月的灰色日期，日历自动跳转到对应月份并选中该日期。无需手动点击箭头导航。

<TCalendar v-model="selectedDate" />

自定义起始日

设置 first-day-of-week="0" 让周日作为每周第一天。

<TCalendar :first-day-of-week="0" show-week />

限制可选范围

通过 min 和 max 限制可选日期的范围。

<TCalendar min="2026-01-01" max="2026-01-31" />

自定义禁用日期

通过 disabled-date prop 传入函数，动态控制哪些日期不可选。

const isWeekend = (date) => {
  const d = new Date(date);
  return d.getDay() === 0 || d.getDay() === 6;
}
<TCalendar :disabled-date="isWeekend" />

范围选择

设置 range 启用范围选择模式。配合 v-model:range-start 和 v-model:range-end 实现双向绑定。点击第一个日期设为起始，点击第二个日期设为结束，第三次点击开启新范围。

const rangeStart = ref('2026-01-01')
const rangeEnd = ref('2026-01-14')

<TCalendar
  range
  v-model:range-start="rangeStart"
  v-model:range-end="rangeEnd"
/>

国际化

通过 locale prop 传入自定义翻译对象，支持星期、月份、按钮文案的完全定制。

const enLocale = {
  weekDays: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'],
  months: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
    'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'],
  today: 'Back to Today',
  week: 'Wk',
  yearFormat: '{y}',
  prevMonth: 'Prev Month',
  nextMonth: 'Next Month',
  prevYear: 'Prev Year',
  nextYear: 'Next Year',
}

<TCalendar :locale="enLocale" show-week />

全屏模式

设置 fullscreen 启用大尺寸日历，适合嵌入页面内容区。

<TCalendar fullscreen />

迷你模式

设置 mini 启用紧凑布局。无内容区、核心信息居中、间距缩小，适合嵌入侧边栏、卡片等小空间。

<TCalendar mini />
<TCalendar mini show-week />
<TCalendar mini mode="year" />

锁定视图

设置 lockView 固定当前视图模式，隐藏模式切换按钮。年视图下点击月份仅导航不切换。

<TCalendar lockView="y" mini />

隐藏视图切换按钮

设置 show-view-switch 为 false 隐藏切换按钮。

<TCalendar :show-view-switch="false" />

周选择模式

设置 week-select 启用周选择。点击任意日期选中整周，v-model 值为 ISO 周格式（如 2026-W29）。

<TCalendar week-select show-week />

周选择自定义格式

通过 week-format 自定义值格式，支持 {y}（年）和 {wk}（周数）占位符。

<TCalendar week-select week-format="{y}年-第{wk}周" show-week />

只读模式

设置 readonly 禁止所有选中操作，适合展示已确定的日期、周、月信息。

<TCalendar :model-value="'2026-06-01'" readonly />
<TCalendar :model-value="'2026-06-01'" readonly mode="year" />
<TCalendar week-select readonly week-format="W{wk}-{y}" show-week />

API

TCalendar 属性 (Props)

属性名	说明	类型	默认值
model-value	选中日期（v-model 绑定，格式 YYYY-MM-DD）	string | null	null
min	最小可选日期	string	undefined
max	最大可选日期	string	undefined
first-day-of-week	每周起始日：0=周日，1=周一	0 | 1	1
disabled-date	自定义禁用日期的函数	(date: string) => boolean	undefined
fullscreen	全屏/大尺寸模式	boolean	false
show-week	显示 ISO 周序号列	boolean	false
range	启用范围选择模式	boolean	false
range-start	范围起始日期（v-model:range-start）	string | null	null
range-end	范围结束日期（v-model:range-end）	string | null	null
mode	视图模式	'year' | 'month' | 'week'	'month'
locale	国际化配置	CalendarLocale	defaultLocale
lock-view	锁定视图：y=年, m=月, w=周	'y' | 'm' | 'w'	undefined
show-view-switch	显示视图切换按钮	boolean	true
mini	迷你模式（无内容区，居中）	boolean	false
week-select	启用周选择模式	boolean	false
week-format	周选择值格式模板	string	'{y}-W{wk}'
readonly	只读模式（禁止选择，仅展示）	boolean	false

TCalendar 事件 (Emits)

事件名	说明	回调参数
update:model-value	单模式选中日期变化	(value: string) => void
update:mode	视图模式变化	(value: 'year' | 'month' | 'week') => void
update:range-start	范围起始变化	(value: string | null) => void
update:range-end	范围结束变化	(value: string | null) => void
change	日期选中时触发	(value: string | { start, end }) => void
panel-change	面板年月切换时触发	(year: number, month: number) => void

TCalendar 插槽 (Slots)

插槽名	说明	作用域参数
cell	完全自定义整个单元格内容	{ day: CalendarDay }：date, day, isCurrentMonth, isToday, isSelected, isDisabled, weekNumber, isRangeStart, isRangeEnd, isInRange
cell-content	自定义单元格主体内容区（年/月/周视图均支持）	{ cell: CalendarDay | CalendarMonthCell | CalendarWeekDay, mode: 'year' | 'month' | 'week' }

TCalendar 暴露的方法 (Expose)

方法名	说明	参数
goToDate	跳转到指定年月	(year: number, month?: number)
goToToday	跳转回今天	-
currentYear	当前展示年份（只读）	-
currentMonthNum	当前展示月份 1-12（只读）	-
resetRange	重置范围选择状态	-