日历是时间管理类应用中最高频的交互界面之一。HarmonyOS NEXT ArkUI 提供了 CalendarPicker 组件以月视图网格的方式展示完整日历支持年份月份滑动切换、日期选中高亮和自定义日期范围。配合事件数据可以轻松构建日程管理、酒店预订、排班管理等场景。本文将深入讲解 CalendarPicker 的核心 API并通过一个完整的日程管理实战案例展示月历视图与事件数据的联动显示。关键词HarmonyOS、ArkUI、CalendarPicker、日历、日程管理、月视图一、CalendarPicker 组件概览CalendarPicker 是 ArkUI 日历时间组件家族中的第三个成员与前两篇文章介绍的 DatePicker 和 TimePicker 不同CalendarPicker 侧重于以月为单位的时间空间可视化。组件交互模式主要用途DatePicker三列滚轮年月日精确日期选择TimePicker两列滚轮时分精确时间选择CalendarPicker月视图网格日期浏览与可视化CalendarPicker 的特点在于一览性——用户不需要滑动滚轮直接在一个月视图网格中看到所有日期及其分布。这对于需要看到某月有哪些日期被占用的场景如日程、排班、预订非常关键。二、CalendarPicker 核心 API2.1 构造函数CalendarPicker({start:Date,// 可选的最早日期end:Date,// 可选的最晚日期selected:Date// 当前选中日期})三个参数与 DatePicker 的构造函数完全一致但组件的视觉呈现完全不同——DatePicker 是滚轮CalendarPicker 是网格。2.2 onChange 回调当用户点击日历网格中的某个日期时onChange被触发返回选中的 Date 对象CalendarPicker({...}).onChange((value:Date){// value 是选中的 Date 对象this.selTimestampvalue.getTime();this.updateEvents(value);})注意onChange的参数类型是Date不是数字时间戳。这与某些其他 ArkUI 组件的回调不同使用时要留意类型匹配。2.3 关键属性属性类型说明.onChange()CallbackDate选中日期变化回调.edgeAlign()CalendarEdgeAlign日期对齐方式.fadeEffect()boolean非当前月日期是否淡化2.4 CalendarEdgeAlign 对齐模式CalendarPicker 支持两种日期对齐模式CalendarEdgeAlign.START日期从左边开始排列CalendarEdgeAlign.END日期从右边开始排列大多数场景使用默认的 START 对齐即可。三、实战日程管理我们实现一个日程管理页面包含CalendarPicker 日历视图按月浏览点击选择日期选中日期信息展示显示选中日期、星期几、当年第几天当日日程列表根据选中日期展示对应的日程事件今天按钮一键跳转回当前日期3.1 事件数据结构事件数据以日期为键MM-DD 格式存储日程的时间、标题和标识颜色interfaceEventItem{date:string;// MM-DDtitle:string;time:string;// 10:00 - 11:30 或 全天color:string;// 左侧色条颜色}privateevents:EventItem[][{date:07-01,title:团队周会 — 产品迭代评审,time:10:00 - 11:30,color:#1677FF},{date:07-03,title:技术分享ArkUI 自定义组件,time:14:00 - 15:00,color:#52C41A},{date:07-07,title:版本 2.5.0 发布上线,time:09:00 - 12:00,color:#FF5722},// ... 更多事件];这个数据结构设计的关键在于date字段使用MM-DD而非完整日期——这样同月同日的事件在不同年份也能匹配同时保持了数据的简洁性。3.2 日期选中处理当用户在日历上点击某个日期时更新选中状态并查询该日期的日程updateSelection(date:Date):void{this.selTimestampdate.getTime();constydate.getFullYear().toString();constm(date.getMonth()1).toString().padStart(2,0);constddate.getDate().toString().padStart(2,0);this.selDateStry.concat(-,m,-,d);constweekdays[周日,周一,周二,周三,周四,周五,周六];this.selWeekdayweekdays[date.getDay()];// 查询当日事件constkeym.concat(-,d);this.selEvents[];for(leti0;ithis.events.length;i){if(this.events[i].datekey){this.selEvents.push(this.events[i]);}}}这里用到的几个关键 JavaScript Date APIdate.getMonth() 1转换为 1-based 月份date.getDay()获取星期几0周日6周六date.getFullYear()获取 4 位年份3.3 当年第几天计算辅助信息展示——计算选中日期是当年的第几天dayOfYear(date:Date):number{conststartnewDate(date.getFullYear(),0,1);returnMath.floor((date.getTime()-start.getTime())/(1000*60*60*24))1;}原理用目标日期的时间戳减去当年 1 月 1 日的时间戳得到毫秒差再换算为天数。加 1 是因为 1 月 1 日是第 1 天而非第 0 天。3.4 CalendarPicker 集成将 CalendarPicker 嵌入页面中指定日期范围和选中日期CalendarPicker({start:newDate(2025,0,1),end:newDate(2027,11,31),selected:newDate(this.selTimestamp)}).onChange((value:Date){this.onCalendarChange(value);})日期范围设置为 2025-2027实际项目中可以根据需求调整。selected通过selTimestamp状态驱动实现今天按钮跳转后的视觉同步。3.5 日程列表渲染根据选中日期动态渲染日程列表每个事件使用左侧色条标识类型if(this.selEvents.length0){Row(){Text(暂无日程安排).fontSize(14).fontColor(#CCCCDD)}.width(100%).height(48).justifyContent(FlexAlign.Center).backgroundColor(#FAFAFC).borderRadius(10)}else{ForEach(this.selEvents,(evt:EventItem){Row(){Row().width(4).height(36).borderRadius(2).backgroundColor(evt.color).margin({right:12})Column(){Text(evt.title).fontSize(14).fontColor(#1a1a2e).fontWeight(FontWeight.Medium).maxLines(1).textOverflow({overflow:TextOverflow.Ellipsis})Text(evt.time).fontSize(11).fontColor(#9999AA)}.alignItems(HorizontalAlign.Start).layoutWeight(1)}.width(100%).padding({top:10,bottom:10,left:12,right:12}).backgroundColor(#FFFFFF).borderRadius(10).margin({bottom:6})},(evt:EventItem,idx:number)idx.toString())}空状态与有数据状态的分支渲染是一个重要的 UX 细节。当选中日期没有日程时不应留白而要明确告知用户暂无日程安排。这种设计让用户确信不是 bug而是这天真的没有安排。3.6 今天按钮一个简单的今天按钮点击后选中日期跳转回当前日期Button(今天).fontSize(13).fontColor(#1677FF).fontWeight(FontWeight.Medium).padding({top:6,bottom:6,left:14,right:14}).borderRadius(14).backgroundColor(#EEF3FF).onClick((){this.goToday();})goToday()调用updateSelection(new Date())同时更新selTimestamp状态CalendarPicker 自动同步选中日期。四、交互流程进入页面CalendarPicker 显示当前月份今天的日期高亮选中日期显示今日信息日程列表展示今日事件浏览月份左右滑动切换月份日历网格更新选择日期点击日历中的某个日期例如 7 月 7 日选中高亮切换下方信息卡片更新为 7 月 7 日的信息日程列表刷新为当日的 1 个事件查看空日期点击没有事件的日期例如 7 月 2 日日程列表显示暂无日程安排返回今天浏览到其他月份后点击今天按钮日历跳回当前月并选中今天五、设计要点总结5.1 数据驱动的日程查询事件数据以MM-DD格式存储查询时直接用字符串拼接匹配。这种设计简单直接适合事件数量在百条以下的场景。对于更大规模的数据数千条可以考虑使用Mapstring, EventItem[]结构优化查询效率。5.2 色条标识日程列表的每个事件使用左侧 4px 宽的色条标识类型——蓝色会议、绿色分享培训、橙红发布重要节点、紫色设计评审、粉色团建活动。色条在视觉上比文字标签更轻量用户扫一眼就能区分事件类型。5.3 空状态处理空状态不是一个边缘情况——对于日程管理来说大多数日期的确是空的。因此空状态的 UI 设计同样重要。使用浅灰底色 居中文字既不被忽略也不抢占视线。六、总结CalendarPicker 是鸿蒙日历时间组件体系中的可视化担当。它不追求精确到分钟的精度那是 TimePicker 的职责也不追求快速输入那是 DatePicker 的特长而是提供一个一览无余的月视图——这正是日程管理、排班预订等场景最需要的。本文通过日程管理这个实战案例覆盖了CalendarPicker 的月视图网格交互onChange回调的类型Date而非number事件数据驱动的高亮与查询空状态与有数据状态的分支渲染今天按钮的状态同步至此鸿蒙日历时间组件三部曲DatePicker、TimePicker、CalendarPicker全部完成。三个组件各司其职组合起来可以构建从日期选择到时间设定再到日历可视化的完整时间交互方案。本文是鸿蒙新特性系列博客的第 19 篇完整代码可在 DevEco Studio 6.1.1 (API 24) 环境中编译运行。Demo 包含 4 个交互点——日历月视图浏览、日期选中与信息展示、日程列表动态渲染、今日按钮跳转——覆盖了日程管理的基础场景。建议读者在此基础上扩展日程添加弹窗表单写入新事件和月份标记在日历网格中显示有事件的日期点作为进阶练习。