# time.almanac — 民俗黄历

轻量、离线的黄历内容库，用于日历、桌面小工具等民俗展示。**不提供严格择日，不对现实事件作吉凶预测。**

## 功能

- 每日宜忌、时辰宜忌。
- 吉神宜趋、凶煞宜忌。
- 建除十二神、十二值神、黄道/黑道。
- 干支、纳音、冲生肖、煞方位。
- 彭祖百忌、胎神占方、二十八宿。
- 喜神、财神、福神、阴阳贵神方位，以及当天节气名称。

核心使用 `time.ganzhi`、`time.sun`、`time.julianDay` 和静态数据，均为纯 aardio。不运行 JS，不访问网络，不加载 .NET。若还要显示“正月初一”等农历日期，按需另外导入 `time.lunar` 即可。

## 快速上手

```aardio
import time.almanac;

var day,err = time.almanac.getDay("2024-06-26");
if(!day){
    print(err);
    return;
}

print(day.date, day.day.name, day.duty ++ "日");
print("宜：", string.join(day.yi,"、"));
print("忌：", string.join(day.ji,"、"));
print("值神：", day.twelveStar, day.ecliptic);
print("冲" ++ day.clash ++ "，煞" ++ day.sha);
```

也可以创建一个日黄历对象，字段与 `getDay` 相同，并提供 `getHours()` 方法：

```aardio
import time.almanac;
var day = time.almanac("2024-06-26");
print(day.yi);
var hours = day.getHours();
print(#hours); // 13
```

## 配合农历日期

```aardio
import time.almanac;
import time.lunar;

var lunar = time.lunar("2033-12-22");
var day = time.almanac.getDay(lunar);
print(tostring(lunar));
print(day.date, day.yi, day.ji);
```

`time.lunar` 使用系统 .NET 组件，属于可选的农历日期层，不是黄历核心的依赖。其日期范围与本库不完全相同：`time.lunar` 从 1901-02-19 开始，而本库从 1901-01-01 开始。

## 固定口径

| 项目 | 约定 |
|---|---|
| 输入与范围 | 公历 1901-01-01 至 2100-12-31；墙钟字段按北京时间理解 |
| 日黄历月界 | 节气月，在交节当天整日切换 |
| 日黄历年界 | 立春当天整日切换；不是农历春节年界 |
| 日黄历日界 | 0 点换日，日黄历不受输入时分秒影响 |
| 时辰宜忌 | 23 点按次日日干支查表，与 `time.ganzhi` 时柱口径一致 |
| 全日时辰 | 按公历当天返回 13 段，早子、晚子分别列出 |
| 空宜忌 | 保留空数组；不擅自填为“诸事不宜”或“无忌” |
| 黄道标识 | `isLucky` 只表示十二值神分类，不代表宜忌综合评分 |

本库不自动换算真太阳时或调整时区。跨时区程序应先准备好北京时间字段，再传入。数值时间戳由 `time` 按系统本地时区解析，因此非北京时间系统更适合传入明确的北京时间字符串或字段表。

民俗体系中可能出现“宜”与彭祖百忌互相矛盾、黄道日仍有忌事项等情况。本库不强行合并或消解这些词条。

## 文档与示例

- [接口与返回字段](api.html)
- [运行窗口示例](demo.html)
- [农历悬浮窗示例](../../../examples/canvas/lunar-float.html)

首次查询一个公历年时计算并缓存节气与月柱；每线程最多缓存 8 年。查询结果是独立快照，修改返回数组或干支字段不会影响后续查询。