鸿蒙万年历应用开发：CalendarEngine与农历算法实战

鸿蒙专家

万年历是移动端高频应用，开发一款功能完整的鸿蒙万年历应用，不仅需要展示公历日期，还要集成农历、节气、传统节日等中国特色功能。本文基于HarmonyOS NEXT（API 20+），从零构建该应用，重点分享CalendarEngine日期计算引擎和农历转换算法的实现思路。

项目采用MVVM架构，数据模型定义如下：DateInfo包含公历/农历年、月、日、星期、节气、节日等字段；ScheduleItem用于日程管理；FestivalInfo存储节日信息。

日历核心引擎CalendarEngine提供基础日期计算能力：

2. // CalendarEngine.ets
3. static DAYS_OF_MONTH: number[] = [31,28,31,30,31,30,31,31,30,31,30,31];
5. static isLeapYear(year: number): boolean {
6.     return (year % 4 === 0 && year % 100 !== 0) || (year % 400 === 0);
7. }
9. static getDaysOfMonth(year: number, month: number): number {
10.     if (month === 2) return this.isLeapYear(year) ? 29 : 28;
11.     return this.DAYS_OF_MONTH[month - 1];
12. }
14. static getFirstDayOfMonth(year: number, month: number): number {
15.     const m = month >= 3 ? month : month + 12;
16.     const y = month >= 3 ? year : year - 1;
17.     const k = y % 100;
18.     const j = Math.floor(y / 100);
19.     const day = 1;
20.     const h = (day + Math.floor(13 * (m + 1) / 5) + k + Math.floor(k / 4) + Math.floor(j / 4) + 5 * j) % 7;
21.     return (h + 6) % 7;
22. }
24. static getMonthGridRows(year: number, month: number): number {
25.     const days = this.getDaysOfMonth(year, month);
26.     const firstDay = this.getFirstDayOfMonth(year, month);
27.     return Math.ceil((days + firstDay) / 7);
28. }
30. static formatDate(year: number, month: number, day: number, sep: string = '-'): string {
31.     return `${year}${sep}${String(month).padStart(2,'0')}${sep}${String(day).padStart(2,'0')}`;
32. }
34. static parseDate(dateStr: string): { year: number; month: number; day: number } {
35.     const parts = dateStr.split('-');
36.     return { year: parseInt(parts[0]), month: parseInt(parts[1]), day: parseInt(parts[2]) };
37. }
39. static daysBetween(date1: string, date2: string): number {
40.     const d1 = this.parseDate(date1);
41.     const d2 = this.parseDate(date2);
42.     const toDays = (y: number, m: number, d: number): number => {
43.         let days = 0;
44.         for (let i = 1970; i < y; i++) days += this.isLeapYear(i) ? 366 : 365;
45.         for (let i = 1; i < m; i++) days += this.getDaysOfMonth(y, i);
46.         return days + d - 1;
47.     };
48.     return Math.abs(toDays(d1.year,d1.month,d1.day) - toDays(d2.year,d2.month,d2.day));
49. }
51. static getToday(): { year: number; month: number; day: number } {
52.     const now = new Date();
53.     return { year: now.getFullYear(), month: now.getMonth()+1, day: now.getDate() };
54. }
56. static getTodayString(): string {
57.     const t = this.getToday();
58.     return this.formatDate(t.year, t.month, t.day);
59. }

复制代码

农历转换是核心难点。LunarDate类基于查表法和位运算实现公历转农历。核心思路：使用lunarInfo数组存储1900-2100年每年农历信息，每个元素的高4位表示闰月月份（0表示无闰月），低12位表示12个月的大小月（1=30天，0=29天），次高4位表示闰月天数。通过计算目标日期与1900年1月31日（农历1900年正月初一）的天数偏移，迭代确定农历年、月、日，并包含节气判断。

2. // LunarDate.ets
3. static LUNAR_MONTH_NAME: string[] = ['','正','二','三','四','五','六','七','八','九','十','冬','腊'];
4. static LUNAR_DAY_NAME: string[] = ['','初一','初二','初三','初四','初五','初六','初七','初八','初九','初十','十一','十二','十三','十四','十五','十六','十七','十八','十九','二十','廿一','廿二','廿三','廿四','廿五','廿六','廿七','廿八','廿九','三十'];
5. static SOLAR_TERM_NAME: string[] = ['小寒','大寒','立春','雨水','惊蛰','春分','清明','谷雨','立夏','小满','芒种','夏至','小暑','大暑','立秋','处暑','白露','秋分','寒露','霜降','立冬','小雪','大雪','冬至'];
7. // lunarInfo数组（完整数据详见原工程）
8. static LUNAR_INFO: number[] = [0x04bd8, 0x04ae0, ...];
10. static toLunar(year: number, month: number, day: number): LunarInfo {
11.     let offset = this.calculateOffset(year, month, day) - 30; // 减去基准日期1900-01-31对应天数
12.     let lunarYear = 1900, lunarMonth = 1, lunarDay = 1, isLeapMonth = false;
13.     while (lunarYear < 2100 && offset > 0) {
14.         const daysInYear = this.getLunarYearDays(lunarYear);
15.         if (offset < daysInYear) break;
16.         offset -= daysInYear;
17.         lunarYear++;
18.     }
19.     const leapMonth = this.getLeapMonth(lunarYear);
20.     const monthDays = this.getLunarYearMonths(lunarYear);
21.     let monthIndex = 1;
22.     while (monthIndex <= 12 && offset > 0) {
23.         if (leapMonth > 0 && monthIndex === leapMonth + 1 && !isLeapMonth) {
24.             isLeapMonth = true;
25.             monthIndex--;
26.             const leapDays = this.getLeapMonthDays(lunarYear);
27.             if (offset < leapDays) break;
28.             offset -= leapDays;
29.         } else {
30.             if (isLeapMonth && monthIndex === leapMonth + 1) isLeapMonth = false;
31.             const normalDays = monthDays[monthIndex - 1];
32.             if (offset < normalDays) break;
33.             offset -= normalDays;
34.         }
35.         monthIndex++;
36.     }
37.     lunarMonth = isLeapMonth ? monthIndex - 1 : monthIndex;
38.     lunarDay = offset + 1;
39.     const solarTerm = this.getSolarTerm(year, month, day);
40.     const festivals = this.getFestivals(year, month, day, lunarMonth, lunarDay, isLeapMonth);
41.     return { lunarYear, lunarMonth, lunarDay, isLeapMonth, lunarMonthName: this.getLunarMonthName(lunarMonth, isLeapMonth), lunarDayName: this.LUNAR_DAY_NAME[lunarDay-1]||'', solarTerm, festivals };
42. }
44. private static calculateOffset(year: number, month: number, day: number): number {
45.     let days = 0;
46.     for (let y = 1900; y < year; y++) days += CalendarEngine.isLeapYear(y) ? 366 : 365;
47.     for (let m = 1; m < month; m++) days += CalendarEngine.getDaysOfMonth(year, m);
48.     days += day;
49.     return days;
50. }
52. private static getLunarYearDays(year: number): number {
53.     const idx = year - 1900;
54.     if (idx < 0 || idx >= this.LUNAR_INFO.length) return 365;
55.     let days = 0;
56.     const info = this.LUNAR_INFO[idx];
57.     for (let i = 0; i < 12; i++) days += (info & (1 << i)) ? 30 : 29;
58.     return days + this.getLeapMonthDays(year);
59. }
61. private static getLeapMonth(year: number): number {
62.     const idx = year - 1900;
63.     if (idx < 0 || idx >= this.LUNAR_INFO.length) return 0;
64.     return (this.LUNAR_INFO[idx] >> 12) & 0x0f;
65. }
67. private static getLeapMonthDays(year: number): number {
68.     const leapMonth = this.getLeapMonth(year);
69.     if (leapMonth === 0) return 0;
70.     const idx = year - 1900;
71.     return (this.LUNAR_INFO[idx] >> 13) & 1 ? 30 : 29;
72. }
74. private static getSolarTerm(year: number, month: number, day: number): string {
75.     // 简化实现：使用SOLAR_TERM_OFFSET表判断日期是否接近标准节气
76.     const index = (month - 1) * 2;
77.     const termDay1 = this.SOLAR_TERM_OFFSET[index];
78.     const termDay2 = this.SOLAR_TERM_OFFSET[index+1];
79.     if (day >= termDay1 - 2 && day <= termDay1 + 2) return this.SOLAR_TERM_NAME[index];
80.     if (day >= termDay2 - 2 && day <= termDay2 + 2) return this.SOLAR_TERM_NAME[index+1];
81.     return '';
82. }

复制代码

在UI层面，利用ArkUI的Grid组件构建月视图，通过CalendarEngine获取每月第一天星期和总天数动态生成网格，每个格子显示公历日期，下方小字显示农历或节气。使用@State和@Link管理选中日期和视图刷新。结合CalendarPicker组件可快速实现日期选择。需要注意的是，HarmonyOS NEXT的Stage模型要求严格声明权限，但万年历应用通常无需特殊权限。日程管理可基于关系型数据库（RDB Store）或首选项（Preferences）实现本地存储，具体可根据数据量选择。

总结：通过CalendarEngine提供的基础日期能力加上LunarDate的农历查表算法，开发者可以快速在鸿蒙应用中集成完整的农历、节气功能。该方案性能稳定，代码复杂度可控，适合直接嵌入生产级应用。后续可继续扩展节日库、倒计时、主题换肤等能力。

热心网友6

楼主分享得很详细，尤其是CalendarEngine里getFirstDayOfMonth用的蔡勒公式变体，以及农历查表法+位运算存储闰月和大小的思路，实际开发中非常实用。想请教一下，lunarInfo数组里节气数据是单独存储的还是和农历信息整合在一起计算的？另外，对于1900年之前或2100年之后的日期，楼主有没有考虑做外推处理，还是直接限制范围？UI层这块，月视图和年视图切换时，按楼主MVVM的结构，数据绑定是直接用@State监听DateInfo的变化吗？