接口与返回字段

接口

接口	返回值
`time.almanac.getDay(date)`	日黄历普通表
`time.almanac(date)`	日黄历对象，另有 `getHours()` 方法
`time.almanac.getHour(date)`	指定时刻的时辰黄历普通表
`time.almanac.getHours(date)`	公历当天按时间排序的 13 段时辰数组
`time.almanac.getSource()`	数据来源、上游版本、哈希和完整 MIT 许可证

date 可省略（当前日期时间），或传入：

time 对象。
YYYY-MM-DD / YYYY/MM/DD 字符串，支持后接 HH:MM:SS，可从右向左省略秒、分、时。
Unix 秒时间戳（经 time 按系统本地时区解析）。
包含公历 year,month,day 及可选 hour,minute,second 的表。
调用者已导入 time.lunar 并创建的农历对象；本库使用它的原始公历日期。

查询函数失败返回 null,err。构造失败返回 null；需要详细错误信息时使用 getDay。不会修改传入的时间对象。

import time.almanac;
var result,err = time.almanac.getDay("2024-02-30");
print(result,err); // null, 公历日期不存在

日黄历字段

字段	类型	内容
`date`	string	公历日期，`YYYY-MM-DD`
`year` / `month` / `day`	table	年/月/日干支信息；年、月是节气年、节气月，不是农历年月
`yi` / `ji`	array	宜/忌词条，保留原表顺序
`goodGods` / `badGods`	array	吉神/凶煞词条，保留原表顺序
`duty`	string	建除十二神，如“平”；展示为“平日”可自行加字
`twelveStar`	string	十二值神，如“明堂”
`ecliptic`	string	“黄道”或“黑道”
`isLucky`	boolean	值神是否为黄道，不是综合结论
`pengZu`	array	彭祖百忌，两条字符串
`fetus`	string	胎神占方，如“厨灶门外东南”
`mansion`	string	二十八宿名称，如“轸”
`mansionFullName`	string	宿名、七曜、动物组合，如“轸水蚓”
`clash`	string	日冲生肖，如“兔”；不包含“冲”字
`sha`	string	日煞方位，如“东”；不包含“煞”字
`joyDirection`	string	喜神方位
`wealthDirection`	string	财神方位
`mascotDirection`	string	福神方位
`yangNobleDirection` / `yinNobleDirection`	string	阳贵神/阴贵神方位
`solarTerm`	string	当天节气名称；没有节气时为 `""`

干支字段

字段	内容
`name`	“甲子”等干支名称
`index`	六十甲子索引 0~59，甲子为 0
`gan` / `zhi`	天干/地支名称
`ganIndex`	天干索引 0~9
`zhiIndex`	地支索引 0~11，子为 0
`nayin`	纳音名称

原表、索引采用 0 起始；aardio 数组本身仍按 1 起始访问。

时辰黄历字段

getHour 返回以下字段：

datetime：原公历墙钟时间字符串。
name：子时、丑时等名称。
day：时宜忌实际使用的日干支，23 点后为次日。
hour：时干支。
dayOffset：晚子为 1，其余为 0；不改变 datetime 的公历日期。
startHour,endHour：公历当天所占时间范围，左闭右开。
yi,ji：时宜、时忌字符串数组。
twelveStar,ecliptic,isLucky：时辰值神与黄道分类。

import time.almanac;
var h = time.almanac.getHour("2024-06-25 23:30:00");
print(h.name, h.hour.name, h.day.name);
print(h.startHour,h.endHour); // 23,24
print(h.dayOffset); // 1
print(h.yi,h.ji);

为什么全日有 13 段

传统子时横跨两个公历日。为了不把当天 0 点和 23 点不同的宜忌混成一条，按当天时间轴分别返回：

第 1 段：早子 [0,1)，按当日日干支。
第 2~12 段：丑、寅、卯、辰、巳、午、未、申、酉、戌、亥，各两小时。
第 13 段：晚子 [23,24)，按次日日干支。

import time.almanac;
var hours = time.almanac.getHours("2024-06-26");
for(i,h in hours){
    print(string.format("%02d:00-%02d:00",h.startHour,h.endHour),
        h.name,h.hour.name,h.yi,h.ji);
}

如只需传统十二时辰，可取第 1~12 段，但应自行决定如何展示晚子；不要假设当天早子和晚子内容相同。

Markdown 格式