wot-design-uni wd-calendar-view 日历面板组件完全指南：多类型选择、范围限制与格式化定制实战

前端UI组件移动开发小程序【免费下载链接】wot-design-uni一个基于Vue3TS开发的uni-app组件库提供70高质量组件支持暗黑模式、国际化和自定义主题。项目地址https://gitcode.com/gh_mirrors/wo/wot-design-uni点击查看免费下载在基于 Vue 3 TypeScript 的 uni-app 项目里日期选择类需求往往不止选一天这么简单考勤打卡要选周、排班要看月、请假审批要选日期区间、业务排期还要精确到时分。wot-design-uni 的wd-calendar-view日历面板组件正是为此设计的核心组件它提供日历单选、多选、范围选择、周维度、月维度等功能并允许开发者基于它封装出高度定制化的业务组件。读完本篇你将掌握wd-calendar-view的全部 9 种选择类型、16 个属性参数、事件与外部方法并理解面板内部的月份布局计算、滚动定位与时间选择器数据过滤机制从而把它落地到真实业务场景。组件定位与内部结构wd-calendar-view与弹出式的 日历选择器wd-calendar不同它是一个常驻在页面中的面板形态组件适合需要与页面其他区域联动展示的场景例如左侧列表 右侧日历的排班页。从源码结构看wd-calendar-view.vue组件根据type自动分发到两套子面板month/year或monthrange类型渲染 year-panel.vue以年为滚动单元每页展示 12 个月份格子其余类型渲染 month-panel.vue以月为滚动单元纵向滚动展示min-date到max-date之间的所有月份每个月份由 month.vue 渲染成 7 列日历格。month-panel.vue中还内嵌了wd-picker-view作为时间选择器仅在datetime/datetimerange类型下显示滚动区域高度由panel-height控制且当出现时间选择器时自动扣除 125px 给时间列。基本使用单日期选择type默认为date类型通过v-model绑定 13 位时间戳同时监听change事件获取选中值。wd-calendar-view v-modelvalue changehandleChange /const value ref(Date.now()) function handleChange({ value }) { console.log(value) }关键取值约束与文档 Attributes 一致定义见 types.tsmin-date最小日期默认为当前日期往前推 6 个月max-date最大日期默认为当前日期往后推 6 个月且为当天 23:59:59见 types.ts 中defaultMaxDate的构造面板只渲染这两个边界之间的日期超界日期会被置为禁用态disabled。文档特别提示min-date和max-date这两个值尽量不要设置过大避免大量数据的计算和传递导致页面性能低下。这与源码实现吻合——month-panel.vue中months是一个 computed会遍历getMonths(minDate, maxDate)生成的每个月并逐月渲染日期格跨度越大生成的 DOM 节点越多。日期多选dates设置type为dates此时value为时间戳数组。点击已选日期会取消选中点击未选日期则追加实现见 month.vue 中handleDatesChangewd-calendar-view typedates v-modelvalue changehandleChange /const value ref([]) function handleChange({ value }) { console.log(value) }多选场景下组件会根据选中日期是否连续自动为每个格子标记start/end/middle/multiple-selected/multiple-middle等类型见 month.vue 中getDatesType用于驱动选中态的圆角、连线样式让连续选中的日期在视觉上形成区间效果。周类型选择week设置type为week类型。如果value有初始值建议将周起始日first-day-of-week设置为 1周一避免选中样式和回显匹配不上。wd-calendar-view typeweek v-modelvalue :first-day-of-week1 changehandleChange /const value ref(Date.now()) function handleChange({ value }) { console.log(value) }从源码看month.vue 中handleWeekChange点击任意一天时组件会用getWeekRange计算该日期所在周的第一天并校验周的第一天是否被禁用若禁用则整周不可选最终 emit 的值是周起始日时间戳getDate(weekStart) 24h。first-day-of-week支持 0~6 任意值 7时会自动取模utils.ts中getWeekRange的处理。月类型选择month设置type为month此时value有值时其值为月的第一天。月类型会自动切换到 year-panel 面板以年为单位滚动wd-calendar-view typemonth v-modelvalue changehandleChange /const value ref(Date.now()) function handleChange({ value }) { console.log(value) }范围选择daterange / weekrange / monthrangetype支持daterange日期范围、weekrange周范围、monthrange月范围此时value为[开始, 结束]数组格式wd-calendar-view typedaterange v-modelvalue changehandleChange /const value ref([]) function handleChange({ value }) { console.log(value) }范围选择的交互状态机在 month.vue 的handleDateRangeChange中实现值得注意的三条规则已选开始日未选结束日时再次点击必须compare -1大于等于开始日才会作为结束日点击更早的日期会重置为新的开始日未开启allow-same-day时点击与开始日相同的天会被直接忽略设置max-range后若所选跨度超限组件会自动把结束日回退到max-range允许的最大日期并用wd-toast弹出range-prompt默认文案为选择天数不能超过 x 天可自定义。日期时间类型datetime / datetimerange设置type为datetime可以选择到时分秒datetimerange则为范围选择。面板底部会出现时间选择器滚动区域相应收缩wd-calendar-view typedatetime v-modelvalue changehandleChange /const value ref() function handleChange({ value }) { console.log(value) }隐藏秒与 time-filter 过滤可以设置hide-second使时间只展示到分钟级别设置time-filter属性可以自定义过滤时分秒选项。该属性接收{ type: string, values: array }参数type取值为hour、minute或secondvalues为 picker 数据列表每项含label/value/disabled见 types.ts 中CalendarItem返回一个新的数组wd-calendar-view typedatetime v-modelvalue changehandleChange hide-second :time-filtertimeFilter /const value ref() const timeFilter ({ type, values }) { if (type minute) { // 只展示 0,10,20,30,40,50 分钟选项 return values.filter((item) { return item.value % 10 0 }) } return values } function handleChange({ value }) { console.log(value) }注意两点以仓库实际实现为准time-filter在 utils.ts 的getTimeData中会被分别以hour、minute、second三种 type 调用hide-second时不调用second因此函数内部必须处理其余分支并原样返回时间选项还会被边界禁用逻辑约束当选中的日期等于min-date或max-date当天时对应的小时/分钟/秒范围会被收窄例如最小日当天只能选该日时刻之后的时间。官方示例页 calendarView/Index.vue 中的timeFilter即按item.value % 10 0过滤分钟可直接参考。范围选择允许选中同一日期设置allow-same-day属性范围选择允许用户选择同一天、同一周、同一个月wd-calendar-view typedaterange v-modelvalue allow-same-day changehandleChange /开启后start与end落在同一天时该格子会被标记为same类型month.vue 中getDatetimeType并展示is-same样式。最大范围限制设置max-range属性限制范围选择的最大跨度wd-calendar-view typedaterange :max-range3 v-modelvalue changehandleChange /超限时的提示文案由range-prompt控制默认随语言包输出选择天数不能超过 x 天见 zh-CN.ts 中rangePrompt。格式化日期formatter设置formatter参数其值为函数类型接收一个对象并返回该对象。对象属性与入参一致可修改以定制展示属性类型说明typeCalendarDayType可选值见下方 CalendarDayTypedatetimestamp13 位的时间戳textstring日期文本内容topInfostring上方提示信息bottomInfostring下方提示信息disabledboolean是否禁用CalendarDayType类型说明selected单日期选中start范围开始日期end范围结束日期middle范围开始与结束之间的日期same范围开始与结束日期同一天current当前日期multiple-middle多日期范围选择开始与结束之间的日期multiple-selected多日期范围选择选中的日期从源码看formatter在每个日期格子生成时都会被调用month.vue 中getFormatterDate先构造基础dayObj再交给props.formatter处理并返回因此你可以在其中动态计算disabled实现某日不可选也可以改text替换格子主文案。若formatter不是函数组件会在控制台报错提示。wd-calendar-view typedaterange v-modelvalue allow-same-day :formatterformatter changehandleChange/wd-calendar-viewconst value ref([]) const formatter (day) { const date new Date(day.date) const now new Date() const year date.getFullYear() const month date.getMonth() const da date.getDate() const nowYear now.getFullYear() const nowMonth now.getMonth() const nowDa now.getDate() if (year nowYear month nowMonth da nowDa) { day.topInfo 今天 } if (month 5 da 18) { day.topInfo 618大促 } if (month 10 da 11) { day.topInfo 京东双11 } if (day.type start) { day.bottomInfo 开始 } if (day.type end) { day.bottomInfo 结束 } if (day.type same) { day.bottomInfo 开始/结束 } return day } function handleChange({ value }) { console.log(value) }上述示例与官方演示页 calendarView/Index.vue 中的formatter完全对应演示页用 i18n 的t()输出文案可以复制运行。展示面板标题与周起始日show-panel-title默认为true面板会自动计算并展示当前滚动到的月份/年份标题month-panel.vue 通过scroll事件累加各月高度判断当前索引不需要时可设为falsewd-calendar-view typedaterange :show-panel-titlefalse v-modelvalue changehandleChange /first-day-of-week设置周起始日默认为 0周日设置为 1 则周一依此类推。它影响日历第一列的偏移计算month.vue 中offset (7 getDay() - firstDayOfWeek) % 7与周头文案getWeekLabel按偏移取语言包中的周几名称。Attributes 属性一览参数说明类型可选值默认值v-model选中值为 13 位时间戳或时间戳数组null / number / array--type日期类型stringdate / dates / datetime / week / month / daterange / datetimerange / weekrange / monthrangedatemin-date最小日期为 13 位时间戳number-当前日期往前推 6 个月max-date最大日期为 13 位时间戳number-当前日期往后推 6 个月first-day-of-week周起始天number-0formatter日期格式化函数function--max-rangetype 为范围选择时有效最大日期范围number--range-prompttype 为范围选择时有效选择超出最大日期范围时的错误提示文案string-选择天数不能超过 x 天allow-same-daytype 为范围选择时有效是否允许选择同一天boolean-falseshow-panel-title是否展示面板标题自动计算当前滚动的日期月份boolean-truedefault-time选中日期所使用的当日内具体时刻string / array-00:00:00panel-height可滚动面板的高度number-378time-filtertype 为 datetime 或 datetimerange 时有效用于过滤时间选择器的数据function--hide-secondtype 为 datetime 或 datetimerange 时有效是否不展示秒修改boolean-falseimmediate-changetype 为 datetime 或 datetimerange 时有效是否在手指松开时立即触发 picker-view 的 change 事件。若不开启则会在滚动动画结束后触发 change 事件1.2.25 版本起提供仅微信小程序和支付宝小程序支持boolean-false补充说明几个容易忽略的参数实现细节default-time默认00:00:00字符串或[开始时刻, 结束时刻]数组。month.vue 中getDate会在选中日期上叠加该时刻范围类型分别用数组首尾并对min-date/max-date做越界钳制——这解释了为什么范围选择的结果时间戳可能不是 0 点整panel-height默认 378px是 scroll-view 的高度月面板出现时间选择器时内部再减 125pximmediate-change透传给底层wd-picker-view控制 change 事件触发时机适合小程序端滚动交互体验调优。Events 事件事件名称说明参数change绑定值变化时触发{ value }除change外从 wd-calendar-view.vue 的defineEmits还可以看到组件额外抛出了pickstart/pickend事件时间选择器开始/结束滚动时触发可用于在用户拖动时间滚轮期间做加载态或防抖处理。Methods 方法与 scrollIntoView方法名称说明参数scrollIntoView使当前日期或者选中日期滚动到可视区域并监听滚动在面板从隐藏状态如 display: none切换为展示状态时调用-通过模板 ref 调用组件实例的scrollIntoView()即可。其底层实现在 month-panel.vue / year-panel.vue 中组件挂载时会自动执行一次定位——取选中值数组取排序后第一个计算其所在月份索引与行偏移逐月累加高度得到scroll-top从而让选中日期进入视口这也意味着当面板被v-show隐藏后再显示时调用一次scrollIntoView()可以恢复正确的滚动位置。外部样式类与测试覆盖类名说明custom-class根节点样式组件还开启了virtualHost: true与styleIsolation: shared见 wd-calendar-view.vue 的 options在微信小程序端可以减少一层包裹节点并允许页面样式穿透便于自定义主题。单测方面tests/components/wd-calendar-view.test.ts 覆盖了基本渲染、日期多选、日期范围选择、周范围选择、月范围选择等场景可作为各type属性组合的回归参考完整可交互演示见官方示例页 src/subPages/calendarView/Index.vue。选型与落地建议需要弹出式日期选择时优先用wd-calendar系列选择器需要页面内常驻、与其他区域联动如班次表格时用本面板组件跨度尽量小把min-date/max-date控制在业务真实范围内可显著减少月份渲染数量范围类业务优先开启allow-same-daymax-range 自定义range-prompt三件套能在交互上闭环最小一天、最大 N 天的约束需要不可选某些日期时直接在formatter里设置day.disabled true这是组件内建且与选中态联动的机制禁用的周首会连带整周不可选。赞分享前端UI组件移动开发小程序【免费下载链接】wot-design-uni一个基于Vue3TS开发的uni-app组件库提供70高质量组件支持暗黑模式、国际化和自定义主题。项目地址https://gitcode.com/gh_mirrors/wo/wot-design-uni点击查看免费下载相关推荐Ant Design Mobile 日历组件 Calendar 完全指南单/范围选择、翻页控制与自定义渲染Ant Design Mobile 日历组件 Calendar 完全指南单/范围选择、翻页控制与自定义渲染 本文以 ant design mobile 仓库中UI组件前端移动开发gpui-kit Calendar 组件实战日期选择、范围限制与自定义样式的完整指南gpui kit Calendar 组件实战日期选择、范围限制与自定义样式的完整指南 导读 Calendar 是 gpui kit 提供的一站式日期控件覆盖桌面应用UI组件前端antd-mobile Calendar 日历组件完整实战指南单选、范围选择与自定义渲染antd mobile Calendar 日历组件完整实战指南单选、范围选择与自定义渲染 Calendar 是 antd mobile 中用于 选择单个日期或UI组件前端移动开发创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考