time.almanac — 民俗黄历

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

功能

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

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

快速上手

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() 方法：

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

配合农历日期

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 按系统本地时区解析，因此非北京时间系统更适合传入明确的北京时间字符串或字段表。

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

文档与示例

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

Markdown 格式