本系列博客将全面剖析一款基于 HarmonyOS 平台开发的「重要日」倒数/正数应用从项目架构到代码实现从技术选型到踩坑经验带你完整了解这款应用的开发全过程。一、项目简介ImportantDays重要日是一款运行在鸿蒙 HarmonyOS 系统上的重要日倒数/正数管理应用。用户可以记录生活中重要的日期——生日、纪念日、考试日、旅行出发日等——应用会自动计算距离这些日期还有多少天或已经过去多少天。核心功能一览功能模块描述重要日列表倒数/正数显示支持置顶和多种排序方式16色颜色选择器为每个重要日自定义颜色标识日历月视图Swiper LazyForEach 无限滚动颜色圆点标记添加/编辑标题、日期、描述、颜色、计数模式、重复类型、提前提醒详情页面大号倒数显示、信息卡片、置顶/删除操作统计面板总计、即将到来、已过、本月统计重复类型不重复 / 每年 / 每月深色模式支持系统深色模式自动切换数据持久化Preferences 本地存储二、技术栈本项目采用以下技术栈平台HarmonyOS语言ArkTS华为为鸿蒙生态推出的 TypeScript 超集UI 框架ArkUI V2ComponentV2、ObservedV2、Trace、Param、Local、Monitor日期库dayjs轻量级日期处理库持久化PreferencesArkData 模块SDK 版本5.0.3(15)三、项目结构ImportantDays/ ├── AppScope/ # 应用级配置 │ ├── app.json5 # 应用配置bundleName、版本等 │ └── resources/ # 应用级资源 │ ├── base/ # 基础资源字符串、颜色、图标 │ └── zh_CN/ # 中文资源 ├── entry/ # 入口模块单模块架构 │ ├── src/main/ │ │ ├── ets/ │ │ │ ├── common/ # 常量和 Tab 配置 │ │ │ │ ├── Constants.ets # 应用常量颜色、日历配置等 │ │ │ │ └── TabList.ets # 底部 Tab 配置 │ │ │ ├── components/ # UI 组件 │ │ │ │ ├── CalendarDataSource.ets # 日历数据源 │ │ │ │ ├── CalendarGridView.ets # 日历网格视图 │ │ │ │ ├── ColorPicker.ets # 颜色选择器 │ │ │ │ ├── DayCard.ets # 重要日卡片 │ │ │ │ └── StatPanel.ets # 统计面板 │ │ │ ├── entryability/ # 入口 Ability │ │ │ ├── entrybackupability/# 备份 Ability │ │ │ ├── model/ # 数据模型 │ │ │ │ ├── AvoidArea.ets # 安全区域模型 │ │ │ │ └── ImportantDay.ets # 重要日数据模型 │ │ │ ├── pages/ # 页面 │ │ │ │ ├── MainEntry.ets # 主入口Tab 导航 │ │ │ │ ├── ImportantDayListPage.ets # 重要日列表页 │ │ │ │ ├── CalendarPage.ets # 日历页 │ │ │ │ ├── DayDetailPage.ets # 详情页 │ │ │ │ ├── AddEditDayPage.ets # 添加/编辑页 │ │ │ │ └── MinePage.ets # 我的页面 │ │ │ ├── types/ # 类型定义 │ │ │ │ └── Types.ets # 接口定义 │ │ │ ├── utils/ # 工具类 │ │ │ │ ├── DateUtil.ets # 日期工具 │ │ │ │ ├── Logger.ets # 日志工具 │ │ │ │ ├── NotificationUtil.ets # 通知工具 │ │ │ │ └── PreferenceUtil.ets # 存储工具 │ │ │ └── viewmodel/ # ViewModel │ │ │ └── MainViewModel.ets # 主 ViewModel │ │ ├── resources/ # 模块资源 │ │ └── module.json5 # 模块配置 │ ├── build-profile.json5 │ ├── hvigorfile.ts │ └── oh-package.json5 ├── build-profile.json5 # 项目构建配置 ├── oh-package.json5 # 项目依赖 ├── hvigorfile.ts ├── hvigor/hvigor-config.json5 └── code-linter.json5四、架构设计4.1 整体架构MVVM 模式本项目采用MVVMModel-View-ViewModel架构模式┌─────────────────────────────────────────────┐ │ View 层 │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ 列表页面 │ │ 日历页面 │ │ 详情页面 │ │ │ └────┬─────┘ └────┬─────┘ └────┬─────┘ │ │ │ │ │ │ │ ┌────┴─────┐ ┌────┴─────┐ ┌────┴─────┐ │ │ │ DayCard │ │Calendar │ │StatPanel │ │ │ │ 组件 │ │Grid组件 │ │ 组件 │ │ │ └────┬─────┘ └────┬─────┘ └────┬─────┘ │ └───────┼────────────┼────────────┼──────────┘ │ │ │ ▼ ▼ ▼ ┌─────────────────────────────────────────────┐ │ ViewModel 层 │ │ MainViewModel (单例模式) │ │ ┌──────────────────────────────────────┐ │ │ │ dayList: ImportantDay[] │ │ │ │ sortType / curTabIndex / selectedId │ │ │ │ CRUD 操作 / 排序 / 统计 / 日历查询 │ │ │ └──────────────────────────────────────┘ │ └───────────────────┬─────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────┐ │ Model 层 │ │ ┌────────────┐ ┌────────────┐ │ │ │ImportantDay│ │ AvoidArea │ │ │ │ 数据模型 │ │ 安全区模型 │ │ │ └────────────┘ └────────────┘ │ │ ┌────────────────────────────────────┐ │ │ │ PreferenceUtil (Preferences存储) │ │ │ └────────────────────────────────────┘ │ └─────────────────────────────────────────────┘4.2 关键设计决策单例 ViewModelMainViewModel采用单例模式全局统一管理数据和状态所有页面共享同一数据源避免数据不一致。ArkUI V2 响应式使用ObservedV2Trace实现数据驱动 UIMonitor监听数据变化自动刷新相比 V1 的ObservedObjectLink更加简洁。Preferences 持久化重要日列表通过 JSON 序列化存储在 Preferences 中简单可靠适合轻量级数据。单模块架构项目只有entry一个模块适合中小型应用减少模块间通信开销。五、应用配置5.1 应用级配置app.json5{ app: { bundleName: com.importantdays.app, vendor: example, versionCode: 1000000, versionName: 1.0.0, icon: $media:layered_image, label: $string:app_name } }5.2 构建配置build-profile.json5{ app: { products: [ { name: default, targetSdkVersion: 5.0.3(15), compatibleSdkVersion: 5.0.3(15), runtimeOS: HarmonyOS, buildOption: { strictMode: { caseSensitiveCheck: true, useNormalizedOHMUrl: true } } } ] } }六、小结本篇作为系列博客的第一篇对 ImportantDays 项目进行了全面的概述。我们从功能列表、技术栈、项目结构到架构设计建立了一个全局视角。接下来的篇章将逐一深入每个模块从环境搭建到代码实现带你完整掌握鸿蒙应用开发的全流程。