跳到主要内容

Calendar 日历 ​

uni-appH5微信小程序App

跨端月历:整月视图选择日期,支持农历与节日显示、代办事件条、节假日「休」/补班「班」角标、可选范围限制与年月翻页。

何时使用 ​

需要整月视图选日期或展示日期维度信息:日程看板、考勤标记、活动日历、农历节日展示、代办事项标记、节假日与补班排班。

何时不使用 ​

表单里单纯录入一个日期用 DatePicker 更省空间;需要选时间用 TimePicker/TimeSelect。

本文档为 uni-app 端组件契约;Web 端同名组件 API 可能略有差异,请以对应包文档为准。下方手机预览实时运行 uni-app H5 演示。

9:41
Calendar 日历 · uni-app H5 实时运行 新窗口打开

Props ​

名称类型默认值说明
modelValuestring | nullnull绑定值,格式 'YYYY-MM-DD',配合 v-model 使用
minstring"''"可选最小日期(含),格式 'YYYY-MM-DD'
maxstring"''"可选最大日期(含),格式 'YYYY-MM-DD'
lunarbooleanfalse是否显示农历:日号下方小字,初一显月份名(正月/腊月/闰五月),传统节日(春节/端午/中秋/除夕等)显节日名并主色高亮。支持 1900-2100
festivalsbooleantrue是否显示公历节日(元旦/劳动节/国庆等,主色高亮),仅在 lunar 开启时生效
events{ date: string; label: string; type?: 'primary' | 'success' | 'warning' | 'danger' }[]"[]"代办事项列表。有事件的格子显示事件条(soft 底 + 色字,单行省略),最多 2 条,超出折叠为 +N
holidaysstring[]"[]"节假日(休息日)日期列表,格式 'YYYY-MM-DD'。这些日期在格子右上角显示红色「休」角标
workdaysstring[]"[]"工作日(补班/调休)日期列表,格式 'YYYY-MM-DD'。这些日期在格子右上角显示「班」角标;同一日期同时命中 holidays 时以 workdays 为准

Events ​

名称载荷说明
update:modelValuestring选中日期时触发
changestring选中日期(含点击「今天」)时触发
panel-change{ year: number; month: number }面板年月切换时触发(翻页/点「今天」),month 为 1-12
event-click(event, day: { date, day, inCurrentMonth, isToday })点击事件条时触发(已 stop,不会触发日期选中)

Slots ​

名称说明
date-cell自定义日期格内容,scope { date, day, isSelected, isToday, inCurrentMonth }。提供插槽时完全接管格子内容,lunar/events 默认渲染不再生效

示例 ​

基础内联日历 ​

vue
<Calendar v-model="calDate" />

农历与休班角标 ​

vue
<Calendar v-model="calDate" lunar :holidays="calHolidays" :workdays="calWorkdays" />

代办事件标记 ​

vue
<Calendar v-model="calDate" :events="calEvents" @event-click="onEventTap" />

农历 + 事件 + 休班 ​

vue
<Calendar v-model="calDate" lunar :events="calEvents" :holidays="calHolidays" :workdays="calWorkdays" />

限定可选范围 ​

vue
<Calendar v-model="calDate" min="2026-08-10" max="2026-09-20" />