Calendar 日历
日历用于以月视图展示日期，适合承载排期、活动、值班、任务计划等按天组织的信息。
基础用法
设置 v-model 可以指定当前显示和选中的日期。未绑定时，日历默认显示当前月份。
vue
<template>
<el-calendar v-model="value" />
</template>
<script setup lang="ts">
import { ref } from 'vue'
const value = ref(new Date())
</script>自定义日期单元格
使用 date-cell 插槽可以自定义每个日期格的内容。插槽参数 data 包含 day、date、type 和 isSelected。
vue
<template>
<el-calendar v-model="value">
<template #date-cell="{ data }">
<div>
<div>{{ Number(data.day.split('-')[2]) }}</div>
<el-tag v-if="events[data.day]" size="small">
{{ events[data.day] }}
</el-tag>
</div>
</template>
</el-calendar>
</template>
<script setup lang="ts">
import { ref } from 'vue'
const value = ref(new Date(2026, 4, 1))
const events = {
'2026-05-08': '评审',
'2026-05-15': '上线',
}
</script>指定范围
设置 range 可以只展示一段日期范围。范围由开始日期和结束日期组成，开始日期应为周起始日，结束日期应为周结束日，跨度不能超过两个月。
vue
<template>
<el-calendar :range="range" />
</template>
<script setup lang="ts">
const range = [
new Date(2026, 4, 4),
new Date(2026, 4, 17),
]
</script>自定义头部
使用 header 插槽可以重写日历头部。通过组件暴露的 selectDate 方法，可以在自定义按钮中切换月份、年份或回到今天。
vue
<template>
<el-calendar ref="calendarRef" v-model="value">
<template #header="{ date }">
<div class="calendar-header">
<span>{{ date }}</span>
<el-button-group>
<el-button size="small" @click="selectDate('prev-month')">上个月</el-button>
<el-button size="small" @click="selectDate('today')">今天</el-button>
<el-button size="small" @click="selectDate('next-month')">下个月</el-button>
</el-button-group>
</div>
</template>
</el-calendar>
</template>
<script setup lang="ts">
import { ref } from 'vue'
type CalendarDateType = 'prev-month' | 'next-month' | 'prev-year' | 'next-year' | 'today'
const value = ref(new Date())
const calendarRef = ref<{ selectDate: (type: CalendarDateType) => void }>()
const selectDate = (type: CalendarDateType) => {
calendarRef.value?.selectDate(type)
}
</script>选择器头部
设置 controller-type="select" 后，头部使用年份和月份选择器切换日期。formatter 可自定义选择器选项的显示文案。
vue
<template>
<el-calendar
v-model="value"
controller-type="select"
:formatter="formatter"
/>
</template>
<script setup lang="ts">
import { ref } from 'vue'
const value = ref(new Date())
const formatter = (value: number, type: 'year' | 'month') => {
return type === 'year' ? `${value} 年` : `${value} 月`
}
</script>选中日期
点击日期单元格会更新绑定值，可以结合其他组件同步展示当前选中的日期。
vue
<template>
<el-alert
:title="`当前选中：${value.toLocaleDateString('zh-CN')}`"
type="info"
:closable="false"
/>
<el-calendar v-model="value" />
</template>API
Calendar 属性
| 属性名 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| model-value / v-model | 绑定值，当前显示并选中的日期 | Date | - |
| range | 时间范围，包含开始日期和结束日期 | [Date, Date] | - |
| controller-type | 日历头部控制器类型 | button | select | button |
| formatter | controller-type 为 select 时格式化年份或月份选项 | Function | - |
Calendar 事件
| 事件名 | 说明 | 类型 |
|---|---|---|
| update:modelValue | 绑定值更新时触发 | Function |
| input | 输入值变化时触发 | Function |
Calendar 插槽
| 插槽名 | 说明 | 参数 |
|---|---|---|
| header | 自定义日历头部内容 | { date } |
| date-cell | 自定义日期单元格内容 | { data } |
Date Cell 参数
| 参数名 | 说明 | 类型 |
|---|---|---|
| data.day | 格式化后的日期，格式为 YYYY-MM-DD | string |
| data.date | 当前单元格对应的日期对象 | Date |
| data.type | 日期所属月份类型 | prev-month | current-month | next-month |
| data.isSelected | 是否为当前选中日期 | boolean |
Calendar 暴露
| 名称 | 说明 | 类型 |
|---|---|---|
| selectedDay | 当前选中的日期 | object |
| pickDay | 选择指定日期 | Function |
| selectDate | 按类型选择日期，支持 prev-month、next-month、prev-year、next-year、today | Function |
| calculateValidatedDateRange | 根据开始日期和结束日期计算有效日期范围 | Function |