---
url: /components/calendar.md
---
# Calendar 日历

月/年双模式日历面板：支持事件标记、禁用日期、周起始日切换与范围限制，可用于日程概览或轻量排期。

## 基础用法

事件按 `date`（`YYYY-MM-DD` 字符串）匹配到格子，`content` 为事件文案，`type` 决定配色（primary / success / warning / danger）；点击事件条触发 `event-click`：

## 禁用日期与范围高亮

`disabled-date` 返回 true 的日期不可选中（此处禁用周末）；`range` 传入起止日期，区间内格子持续高亮：

## 年视图与实例方法

通过 ref 调用 `setMode` / `today` 等实例方法；年视图为 12 个月的迷你格（有事件的日期带标记点），点任意月份回到月视图，`panel-change` 回报当前面板年月：

## 自定义单元格

`date-cell` 插槽接管格子内容，`data` 携带 `day` / `date` / `isToday` / `isCurrentMonth` / `events`，适合加假期标记、角标等自定义内容：

## Calendar API

| 名称 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| modelValue | Date | 今天 | 当前选中日期（v-model） |
| mode | String | `month` | month / year |
| events | Array | `[]` | 事件项 `{ date: 'YYYY-MM-DD', content, type, id?, class? }` |
| disabled-date | Function | — | `(date) => boolean` 禁用日期 |
| first-day-of-week | Number | `1` | 周起始：0 周日 / 1 周一 |
| range | Array | — | 可选范围 `[start, end]`，区间内格子高亮 |
| weekdays | Array | — | 自定义周标签（默认一至日） |
| title-format | Function | — | `(year, month) => string` 自定义标题文案 |

事件：`select(date, { source })`、`panel-change({ year, month })`、`event-click(event, cell)`。

实例方法：`prev()` / `next()` / `today()` / `setMode('month' | 'year')`。

插槽：`header`（作用域含 `title` / `year` / `month` / `mode` 与 `prev` / `next` / `today` / `setMode`）、`date-cell`（作用域为格子数据）。