鸿蒙万年历应用模板：日期切换、黄历与日程的模块拆分实战

本文基于鸿蒙开发实践中心的万年历应用模板（HarmonyOS-APPTMPL-Calendar），拆解一个看似简单、实则处处是状态管理的日历应用：日期、农历、黄历宜忌与日程提醒如何分工、如何联动。

一、一个日历应用，到底有几块状态

万年历模板的入口是 EntryAbility，首页 Index.ets 只做一件事：装进 tab 导航页，并把底部导航栏的 currentIndex 与之同步。业务分在 features 模块的三个一级页面：

• perpetual：万年历主页，默认选中当天；
• almanac：黄历页，按日期展示宜、忌、五行、冲煞；
• mine：我的日程，用端侧关系型数据库（RDB）保存。

数据库存取放在 components，格式化放在 commons，农历换算交给三方库 lunar。首页不写业务，模块不写界面，日历的“面”和“里”就此分开。

二、日期切换：选中态是唯一的事实来源

万年历的核心状态只有一个：当前选中的日期。主页面默认选中当天，切换时只改这一个值；黄历和日程页监听它、按它重新取数。联动因此不会乱：

1. 黄历页只按选中日期取记录；
2. 日程页按选中日期过滤提醒，新增后返回列表，看到的仍是同一天；
3. 底部导航切换页签时不重置日期，回到万年历还是原来选中的那一天。

谁改日期，谁负责通知；谁展示数据，谁按日期取数。把选中日期抬成唯一的事实来源，是日历类应用最不容易翻车的做法。

三、黄历：按日期派生的数据，不要存成状态

黄历页的宜忌、五行、冲煞都属于“按日期算出来的结果”，不是用户输入的数据。模板的做法是：以选中日期为查询条件取对应记录，再格式化渲染；黄历页本身不写回任何数据。

能由日期派生出来的，就不要再存一份。存两份的代价，是切换日期时必须两处同步，漏一处就会出现“日历显示 13 号、黄历显示 12 号”的诡异状态。派生数据随取随算，状态越少，BUG 越少。

四、日程：端侧存取，写完立即读回来

我的日程放在 mine 模块，存取集中在 components 的入库层，底层用端侧关系型数据库。写入发生在新增提醒时，读取发生在列表页和月视图的角标上。

模板有个细节值得借鉴：新增提醒提交后，页面不只靠本地追加一条记录“假装成功”，而是回到列表页重新读取当日数据，再决定显示什么。看起来多读了一次，换来两个确定性：写失败，列表不会凭空多一条；写成功，列表和月视图角标一定一致。

五、复用这套模板，要注意三个边界

第一，数据来源。首页、日历、黄历的数据都用到 DataMock 样例数据，展示的是 2024 年固定年份的内容。复用时先确认哪些是样例、哪些是真实逻辑，别把样例年份当成动态数据。

第二，账户登录。模板里的登录是模拟登录，不做真实账号校验，也没有网络请求。做成正式应用时，登录态、日程同步、广告位都要重新接真实服务。

第三，广告位。底部弹窗和 banner 目前展示示例图片，测试位没有收益用途。上线前按广告平台的接入文档替换，并确认广告出现时机不遮挡日历切换和添加日程的入口。

六、小结

万年历模板看起来是“一个日历加三个页签”，实际是四层分工的示范：首页只管导航，功能页只管展示，数据库存取集中在 components，农历换算交给 lunar。再加两条纪律：选中日期是唯一事实来源，派生数据随取随算。写日历类应用，先把这四层和两条纪律想清楚，再写界面，比一上来画月视图省事得多。