Calendar 日历
uni-appH5微信小程序App
跨端月历:整月视图选择日期,支持农历与节日显示、代办事件条、节假日「休」/补班「班」角标、可选范围限制与年月翻页。
何时使用
需要整月视图选日期或展示日期维度信息:日程看板、考勤标记、活动日历、农历节日展示、代办事项标记、节假日与补班排班。
何时不使用
表单里单纯录入一个日期用 DatePicker 更省空间;需要选时间用 TimePicker/TimeSelect。
本文档为 uni-app 端组件契约;Web 端同名组件 API 可能略有差异,请以对应包文档为准。下方手机预览实时运行 uni-app H5 演示。
Props
| 名称 | 类型 | 默认值 | 说明 |
|---|---|---|---|
modelValue | string | null | null | 绑定值,格式 'YYYY-MM-DD',配合 v-model 使用 |
min | string | "''" | 可选最小日期(含),格式 'YYYY-MM-DD' |
max | string | "''" | 可选最大日期(含),格式 'YYYY-MM-DD' |
lunar | boolean | false | 是否显示农历:日号下方小字,初一显月份名(正月/腊月/闰五月),传统节日(春节/端午/中秋/除夕等)显节日名并主色高亮。支持 1900-2100 |
festivals | boolean | true | 是否显示公历节日(元旦/劳动节/国庆等,主色高亮),仅在 lunar 开启时生效 |
events | { date: string; label: string; type?: 'primary' | 'success' | 'warning' | 'danger' }[] | "[]" | 代办事项列表。有事件的格子显示事件条(soft 底 + 色字,单行省略),最多 2 条,超出折叠为 +N |
holidays | string[] | "[]" | 节假日(休息日)日期列表,格式 'YYYY-MM-DD'。这些日期在格子右上角显示红色「休」角标 |
workdays | string[] | "[]" | 工作日(补班/调休)日期列表,格式 'YYYY-MM-DD'。这些日期在格子右上角显示「班」角标;同一日期同时命中 holidays 时以 workdays 为准 |
Events
| 名称 | 载荷 | 说明 |
|---|---|---|
update:modelValue | string | 选中日期时触发 |
change | string | 选中日期(含点击「今天」)时触发 |
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" />