LUNAR_CALENDAR.md 3.18 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110
# 农历日期计算功能

本文档介绍了日历应用中的农历日期计算功能。

## 功能概述

农历日期计算功能允许应用显示与公历日期对应的农历日期信息,包括:

- 农历年(天干地支,如"甲辰年")
- 生肖(如"龙")
- 农历月(如"正月")
- 农历日(如"初一")

## 实现方式

农历日期的计算主要通过两种方式实现:

1. **配置数据驱动**:对于已知年份,从配置文件中查找预设的农历日期映射。
2. **简化计算回退**:对于配置中不存在的年份,使用简化的计算方法估算农历日期。

## 配置文件结构

农历数据存储在 `src/data/calendar-config.json` 文件中,主要包含以下内容:

```json
{
  "lunarDateMap": {
    "2024": {
      "0101": { "lunarMonth": "腊", "lunarDay": "廿一" },
      ...更多日期...
    },
    "2025": {
      "0101": { "lunarMonth": "腊", "lunarDay": "初二" },
      ...更多日期...
    }
  }
}
```

配置结构说明:

1. `lunarDateMap`:顶层对象,包含各年份的农历数据
2. 年份(如`"2024"`):包含该年全年的农历日期映射
3. 日期格式为`"MMDD"`:月和日都使用两位数表示,如`"0101"`表示1月1日
4. 每个日期映射包含:
   - `lunarMonth`:农历月份(如"正"、"二"、"腊"等)
   - `lunarDay`:农历日期(如"初一"、"十五"、"廿九"等)

## 如何使用

### 基本用法

```javascript
import { getLunarDate } from './js/lunarCalendar.js';
import calendarConfig from './data/calendar-config.json';

// 创建一个日期对象
const date = new Date(2024, 0, 1); // 2024年1月1日

// 获取农历日期
const lunarDate = getLunarDate(date, calendarConfig);

console.log(lunarDate.year);   // "甲辰年"
console.log(lunarDate.animal); // "龙"
console.log(lunarDate.month);  // "腊月"
console.log(lunarDate.day);    // "廿一"
```

### 返回值说明

`getLunarDate` 函数返回一个包含以下属性的对象:

- `year`:农历年(天干地支年,如"甲辰年")
- `animal`:生肖(如"龙")
- `month`:农历月(如"正月")
- `day`:农历日(如"初一")

## 如何扩展数据

若要为新的年份添加农历数据,请按以下步骤操作:

1. 打开 `src/data/calendar-config.json` 文件
2.`lunarDateMap` 对象中添加新的年份条目:

```json
"lunarDateMap": {
  "2024": { ... },
  "2025": { ... },
  "2026": {
    "0101": { "lunarMonth": "冬", "lunarDay": "十三" },
    "0102": { "lunarMonth": "冬", "lunarDay": "十四" },
    ...
  }
}
```

添加数据时,请确保:
- 月日格式为 `MMDD`(两位数月份和两位数日期)
- 提供准确的农历月份和日期信息

## 测试

可以通过访问 `src/test-lunar.html` 页面来测试农历日期计算功能。该页面会展示几个测试案例,包括配置中存在和不存在的日期。

## 注意事项

1. 简化计算方法仅作为回退机制,不保证准确性
2. 实际农历计算涉及闰月、大小月以及二十四节气等复杂因素
3. 为获得最佳结果,建议为所有需要支持的年份提供完整的配置数据
4. 农历年份的计算(特别是农历年的开始和结束)依赖于农历月份信息