一、uView Pro 的 Calendar 组件在uni-app 开发中日期选择是一个高频需求场景。无论是酒店预订的入住离店时间选择、电商平台的商品预约、还是日常应用的打卡签到一个功能完善、体验优秀的日历组件都是必不可少的。uView Pro 作为 uni-app 生态中备受关注的Vue3 组件库其Calendar 日历组件经过了多个版本的迭代优化从最初的基础日期选择逐步演进为支持农历显示、打卡签到、节假日标记、自定义价格日历等丰富功能的综合型组件。本文将深入解析 uView Pro Calendar 组件的核心特性、实现原理以及实际应用场景帮助你快速掌握这个强大的日期选择利器。二、组件概览功能特性总览uView Pro 的 Calendar 日历组件具有以下核心特性基础功能✅ 支持单日期选择和日期范围选择两种模式✅ 底部弹窗和页面嵌入两种展示方式✅ 年月切换导航支持自定义年份范围✅ 日期范围限制防止选择无效日期进阶功能✅ 农历显示支持自动计算农历日期✅ 打卡签到模式支持已打卡/未打卡状态展示✅ 节假日和加班日标记显示休/班标识✅ 内置中国传统节日支持自定义节日配置✅ 自定义日期内容插槽适用于价格日历等场景交互优化✅ 默认选中今天支持指定默认日期✅ 只读模式禁止日期选择✅ 选中效果可配置适应不同视觉需求三、基础使用快速上手3.1 单日期选择模式单日期选择是最常用的场景比如选择生日、预约日期等。template view u-calendar v-modelshow modedate changeonChange/u-calendar u-button clickshow true选择日期/u-button /view /template script setup langts import { ref } from vue import type { CalendarChangeDate } from uview-pro/types/global const show ref(false) function onChange(e: CalendarChangeDate) { console.log(选择的日期, e.result) console.log(星期, e.week) console.log(是否今天, e.isToday) } /script回调参数说明属性说明类型year选择的年份numbermonth选择的月份numberday选择的日期numberresult格式化的日期字符串如 2024-06-15stringweek星期文字如 星期六stringisToday是否选择了今天boolean3.2 日期范围选择模式范围选择适用于酒店预订、行程规划等需要起止时间的场景。template u-calendar v-modelshow moderange start-text入住 end-text离店 changeonRangeChange template #tooltip view classtip请选择入住和离店时间/view /template /u-calendar /template script setup langts import { ref } from vue import type { CalendarChangeRange } from uview-pro/types/global const show ref(false) function onRangeChange(e: CalendarChangeRange) { console.log(入住日期, e.startDate) console.log(离店日期, e.endDate) console.log(共, e.endDay - e.startDay 1, 晚) } /script范围模式回调参数属性说明startDate / endDate起始/结束日期字符串startYear / endYear起始/结束年份startMonth / endMonth起始/结束月份startDay / endDay起始/结束日期startWeek / endWeek起始/结束星期四、进阶功能详解4.1 农历显示Calendar 组件内置了农历计算功能开启后会自动显示农历日期。u-calendar v-modelshow modedate :show-lunartrue changeonLunarChange /u-calendar开启农历后回调参数会增加lunar对象{ day: 15, month: 6, result: 2024-06-15, lunar: { dayCn: 初十, // 农历日 monthCn: 五月, // 农历月 year: 2024, // 农历年 weekCn: 星期六 // 农历星期 } }农历显示会自动处理闰月、大小月等复杂逻辑无需开发者关心底层实现。4.2 页面嵌入模式除了弹窗模式组件还支持直接嵌入页面显示适用于需要常驻展示日历的场景。template view classcalendar-page u-calendar :is-pagetrue modedate changeonChange /u-calendar /view /template页面模式的特点不显示弹窗和确定按钮选择日期后自动触发change事件支持所有其他功能农历、打卡、节假日等4.3 打卡签到模式打卡签到日历也是近期咨询我比较多的功能Calendar 组件专门为此设计了打卡模式。template u-calendar :is-pagetrue :checkin-modetrue :checked-datescheckedDates :today-checkedtodayChecked /u-calendar /template script setup import { ref } from vue // 已打卡日期列表 const checkedDates ref([ 2024-01-01, 2024-01-02, 2024-01-03, 2024-01-05 ]) // 今日打卡状态优先级高于自动判断 const todayChecked ref(true) /script打卡模式的显示规则今日已打卡绿色圆形背景显示白色对勾其他已打卡日期橙色圆形背景显示日期未打卡日期checkin-mode为 true 时灰色圆形背景颜色自定义属性说明默认值checked-bg-color已打卡日期背景色橙色warningtoday-checked-bg-color今日已打卡背景色绿色successunchecked-bg-color未打卡日期背景色灰色light4.4 节假日与加班日标记组件支持显示节假日和加班日标记方便用户了解日期属性。template u-calendar :is-pagetrue :holidaysholidays :workdaysworkdays /u-calendar /template script setup import { ref } from vue // 节假日元旦假期 const holidays ref([2024-01-01, 2024-01-02]) // 加班日调休上班 const workdays ref([2024-01-06, 2024-01-07]) /script显示效果节假日日期右上角显示红色休字加班日日期右上角显示蓝色班字选中状态下休/班字变为白色4.5 节日显示组件内置了中国传统节日同时支持自定义节日配置。内置节日show-festival为 true 时自动显示元旦1月1日情人节2月14日妇女节3月8日植树节3月12日愚人节4月1日劳动节5月1日青年节5月4日儿童节6月1日建党节7月1日建军节8月1日教师节9月10日国庆节10月1日光棍节11月11日圣诞节12月25日自定义节日template u-calendar :is-pagetrue :show-festivaltrue :festivalscustomFestivals /u-calendar /template script setup import { ref } from vue const customFestivals ref({ // 每年固定节日MM-DD 格式 04-04: 清明节, 05-05: 端午节, 08-15: 中秋节, // 特定年份节日YYYY-MM-DD 格式- 优先级更高 2025-04-04: 清明节2025, // 覆盖内置节日传入空字符串不显示 02-14: , }) /script优先级规则特定年份格式YYYY-MM-DD优先级最高每年固定格式MM-DD次之内置节日优先级最低4.6 自定义日期内容价格日历通过date插槽可以完全自定义每个日期的显示内容常用于电商价格日历场景。template u-calendar :is-pagetrue modedate :use-date-slottrue template #date{ date } text :classgetPriceClass(date) {{ getPriceText(date) }} /text /template /u-calendar /template script setup import { ref } from vue // 价格数据 const priceMap ref({ 2024-01-01: 299, 2024-01-02: 399, 2024-01-03: 359, // ... }) function getPriceText(date) { if (date.isToday) return 今天 const price priceMap.value[date.date] return price ? ¥${price} : } function getPriceClass(date) { if (date.isSelected) return price-selected if (date.isToday) return price-today return price-normal } /script style scoped .price-today { color: #19be6b; font-weight: bold; } .price-normal { color: #909399; font-size: 22rpx; } .price-selected { color: #ffffff; } /style插槽作用域参数属性说明类型date.year年份numberdate.month月份numberdate.day日期numberdate.date完整日期字符串stringdate.week星期文字stringdate.isToday是否今天booleandate.isHoliday是否节假日booleandate.isWorkday是否加班日booleandate.isChecked是否已打卡booleandate.isSelected是否选中booleandate.lunar农历信息object五、核心实现原理浅析5.1 日历渲染逻辑Calendar 组件的日历渲染基于以下核心算法// 获取某月天数 function getMonthDay(year: number, month: number) { return new Date(year, month, 0).getDate() } // 获取某月第一天星期几0-6 function getWeekday(year: number, month: number) { let date new Date(${year}/${month}/01 00:00:00) return date.getDay() }渲染流程计算当月第一天是星期几生成前置空白格子计算当月总天数生成日期格子根据选中状态计算每个格子的样式如果有农历调用农历转换库计算农历日期5.2 农历计算组件使用了独立的农历计算工具Calendar.solar2lunar将公历日期转换为农历function getLunar(year: any, month: any, day: any) { const val Calendar.solar2lunar(year, month, day) return { dayCn: val.IDayCn, // 农历日初十、廿三等 monthCn: val.IMonthCn, // 农历月正月、五月等 weekCn: val.ncWeek, // 农历星期 day: val.lDay, // 农历日数字 month: val.lMonth, // 农历月数字 year: val.lYear // 农历年 } }5.3 范围选择逻辑范围选择采用两次点击确定起止时间的交互方式function dateClick(dayIdx: number) { const d dayIdx 1 const date ${year.value}-${month.value}-${d} if (props.mode range) { // 判断是设置开始日期还是结束日期 const compare new Date(date).getTime() new Date(startDate.value).getTime() if (isStart.value || compare) { // 设置开始日期 startDate.value date isStart.value false } else { // 设置结束日期 endDate.value date isStart.value true // 触发回调 if (props.isPage) btnFix(true) } } }六、实际应用场景6.1 酒店预订日历u-calendar v-modelshow moderange start-text入住 end-text离店 :min-dateminDate :max-datemaxDate changeonDateChange template #tooltip view classhotel-tip text请选择入住和离店日期/text text classsub入住时间14:00后离店时间12:00前/text /view /template /u-calendar6.2 健身打卡应用u-calendar :is-pagetrue :checkin-modetrue :checked-datesmonthCheckins :today-checkedtodayChecked :show-lunartrue changeonCheckin /u-calendar6.3 航班价格日历u-calendar :is-pagetrue modedate :use-date-slottrue :default-select-todayfalse :is-active-currentfalse template #date{ date } view classflight-price text classday{{ date.day }}/text text classprice v-ifgetPrice(date.date) ¥{{ getPrice(date.date) }} /text /view /template /u-calendar6.4 日程管理应用u-calendar :is-pagetrue :show-festivaltrue :festivalscustomFestivals :holidaysholidays :workdaysworkdays :default-dateselectedDate changeonSelectDate /u-calendar七、API 完整参考Props 属性参数说明类型默认值v-model控制弹窗显示/隐藏booleanfalsemode选择模式date 单选 / range 范围stringdateis-page是否在页面中直接显示booleanfalseshow-lunar是否显示农历booleanfalsereadonly是否只读booleanfalsedefault-date默认选中日期单选模式string-start-date默认开始日期范围模式string-end-date默认结束日期范围模式string-default-select-today默认选中今天booleantruemin-date最小可选日期string1950-01-01max-date最大可选日期string今天min-year最小可选年份number/string1950max-year最大可选年份number/string2050change-year是否显示年份切换按钮booleantruechange-month是否显示月份切换按钮booleantrueactive-bg-color选中日期背景色string主题色active-color选中日期文字颜色string白色range-bg-color范围内日期背景色string主题色浅range-color范围内日期文字颜色string主题色start-text开始日期提示文字string开始end-text结束日期提示文字string结束tool-tip顶部提示文字string选择日期closeable是否显示关闭图标booleantruemask-close-able点击遮罩是否关闭booleantruesafe-area-inset-bottom底部安全区适配booleanfalseborder-radius弹窗圆角number/string20z-index弹窗层级number/string10075is-active-current选中日期是否高亮booleantruecheckin-mode是否启用打卡模式booleanfalsechecked-dates已打卡日期列表array[]today-checked今日是否已打卡booleanfalsechecked-bg-color已打卡背景色string橙色today-checked-bg-color今日已打卡背景色string绿色unchecked-bg-color未打卡背景色string灰色holidays节假日列表array[]workdays加班日列表array[]holiday-color节假日文字颜色string红色workday-color加班日文字颜色string蓝色show-festival是否显示内置节日booleanfalsefestivals自定义节日配置object{}festival-color节日文字颜色string主题色use-date-slot是否启用日期插槽booleanfalseEvents 事件事件名说明回调参数change日期选择完成时触发CalendarChangeDate / CalendarChangeRangeSlots 插槽名称说明tooltip自定义顶部提示内容date自定义日期内容作用域插槽八、总结uView Pro 的 Calendar 日历组件是一个功能全面、设计精良的日期选择解决方案。从基础的单日期选择到复杂的打卡签到、价格日历这些都能轻松应对。使用建议选择合适的展示模式弹窗模式适合临时选择页面模式适合常驻展示合理利用默认选中通过default-date或default-select-today提升用户体验注意日期格式所有日期参数统一使用YYYY-MM-DD格式自定义插槽优先级使用date插槽时会覆盖农历、节日等默认显示打卡模式注意today-checked优先级高于checkedDates的自动判断功能使用建议如需农历功能请确保使用支持该功能的版本如需打卡签到、节假日、自定义插槽等高级功能请使用最新版本如果你正在开发 uni-app 项目需要一个功能强大、易于定制的日历组件uView Pro 的 Calendar 值得一试快来体验一下。