# 接口与返回字段

## 接口

| 接口 | 返回值 |
|---|---|
| `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`。不会修改传入的时间对象。

```aardio
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`：时辰值神与黄道分类。

```aardio
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)`，按次日日干支。

```aardio
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 段，但应自行决定如何展示晚子；不要假设当天早子和晚子内容相同。