模組:SuiStar/doc
这是Module:SuiStar的文档页面
 | 此頁面是Module:SuiStar的模块文档。 此頁面可能包含了模板的使用說明、分類和其他内容。 |
本模块实现中国岁星纪年体系的计算，包含木星真实黄经推算、岁星所躔（十二次·十二辰·二十八宿）判定，以及核心的经说/今说双轨制太岁算法。模块为自包含设计，不依赖其他模块。
概述
[编辑]时区默认 UTC+8：
- 岁星几何：木星视黄经、日行速度
- 岁星所躔：所在十二次、十二辰、入二十八宿及距度
- 经说（古籍本义）：太岁 = 岁星所居辰（同辰系），配岁阴、岁阳、岁名全称
- 今说（现代反推）：太岁 = 岁星对冲辰（辰+6 位），虚拟太阴
- 交叉与分野：十二次配国（分野）、岁建/岁破
参数说明
[编辑]所有公开接口均接受以下 frame.args 参数：
| 参数 | 含义 | 类型 | 默认 |
|---|---|---|---|
year |
年份 | 数字 | 当前年 |
month |
月份（1–12） | 数字 | 当前月 |
day |
日期（1–31） | 数字 | 当日 |
hour |
小时（0–23，UTC+8） | 数字 | 12 |
mode |
输出模式（仅 short 接口），可选值：both（经说+今说）、jing（仅经说）、jin（仅今说）。 |
字符串 | both
|
track |
别名版本（erya/shiji），可选值：erya（《尔雅·释天》系）、shiji（《史记·历书》异文系）。 |
字符串 | erya
|
字段清单（供 p.get 调用）
[编辑]岁星几何位置
[编辑]| 字段 | 含义 | 单位 |
|---|---|---|
jupiter_lon |
木星视黄经 | ° |
jupiter_speed |
木星日行速度 | °/日 |
岁星所躔（经今同）
[编辑]| 字段 | 含义 |
|---|---|
sui_xingci |
岁星所在十二次 |
sui_chen |
岁星所在十二辰 |
sui_xiu |
岁星所入二十八宿 |
sui_xiu_in_deg |
入宿距度 |
经说（古籍本义）
[编辑]| 字段 | 含义 |
|---|---|
jingshuo_taisui_chen |
太岁所值辰（= 岁星所居辰，同辰系） |
jingshuo_suiyin |
岁阴（十二辰别名） |
jingshuo_suiyang |
岁阳（十干别名） |
jingshuo_nianhao |
岁名全称（岁阳+岁阴） |
jingshuo_source |
出处与算法说明 |
今说（现代反推）
[编辑]| 字段 | 含义 |
|---|---|
jinshuo_taisui_chen |
太岁所值辰（= 岁星对冲辰，辰+6） |
jinshuo_suiyin |
岁阴 |
jinshuo_nianhao |
岁名全称 |
jinshuo_note |
对冲原理说明 |
交叉与分野
[编辑]| 字段 | 含义 |
|---|---|
xingfen |
岁星所在次分野之国 |
jian_chu |
岁建 / 岁破 |
公开接口
[编辑]| 接口 | 说明 | 示例 |
|---|---|---|
p.compute |
内部主计算，返回全部字段表 | — |
p.get |
取任意单个字段 | {{#invoke:SuiStar|get|param=jingshuo_nianhao}}
|
p.getJD |
取指定时刻儒略日 | {{#invoke:SuiStar|getJD|year=2026}}
|
p.infoBox |
完整信息框（全面版） | {{#invoke:SuiStar|infoBox|year=2026}}
|
p.short |
简洁文本（mode=both/jing/jin） | {{#invoke:SuiStar|short|year=2026|mode=both}}
|
p.suiTable |
经说/今说对照表 | {{#invoke:SuiStar|suiTable|year=2026}}
|
示例
[编辑]- 岁星所在次：
{{#invoke:SuiStar|get|param=sui_xingci}}→ 鹑首 - 经说岁名：
{{#invoke:SuiStar|get|param=jingshuo_nianhao}}→ 旃蒙协洽 - 今说岁名：
{{#invoke:SuiStar|get|param=jinshuo_nianhao}}→ 旃蒙赤奋若 - 简洁文本（双轨）：
{{#invoke:SuiStar|short|year=2026|mode=both}}→ 岁星在鹑首（未）· 入虚宿8.57°；经说太岁在未（旃蒙协洽），今说太岁在丑（旃蒙赤奋若）；分野秦 - 经说/今说对照表：
{{#invoke:SuiStar|suiTable|year=2026}}→
| 经说（古籍本义） | 今说（现代反推） |
|---|---|
| 太岁在『未』 旃蒙协洽 |
太岁在『丑』 旃蒙赤奋若 |
| 经说：太岁左行、岁星右行；太岁辰 = 岁星所居辰（同辰系，《史记·天官书》《淮南子·天文训》本义） 今说：太岁 = 岁星对冲辰（黄经+180°，辰+6 位），现代天文反推之虚拟太阴 | |
- 取儒略日：
{{#invoke:SuiStar|getJD|year=2026|month=10|day=23|hour=12}}→ 2461337 - 完整信息框：
{{#invoke:SuiStar|infoBox|year=2026|month=10|day=23|track=erya}}→
模板
[编辑]本模块配套两个模板。
全面版：完整岁星信息框，包含岁星位置、经说今说双轨太岁、分野、岁建岁破。
{{SuiStarall}}
- 调用：
{{SuiStarall|year=2026|month=10|day=23|hour=12|track=erya}} - 参数：
year/month/day/hour（可选，默认当前时间）、track（erya/shiji，默认erya）
简洁版：输出一行核心结论，可切换经说/今说/双轨。
{{SuiStarJJ}}
- 调用：
{{:SuiStarJJ|year=2026|mode=both|track=erya}} - 参数：
year/month/day/hour（可选）、mode（both/jing/jin，默认both）、track（默认erya）
算法说明
[编辑]木星黄经
[编辑]采用 VSOP87 思路的截断近似：平黄经（起算 34.3515°，速率 3034.9057°/世纪）叠加 6 项主要周期项，精度约 ±0.1°，足以判定十二次与二十八宿。
经说（同辰系）
[编辑]太岁左行、岁星右行。岁星位于某辰，太岁即居同辰。这是《史记·天官书》《淮南子·天文训》的本义。
今说（对冲系）
[编辑]太岁 = 岁星对冲辰，即黄经 +180°，十二辰 +6 位。此为现代天文反推的虚拟太阴模型，与古籍本义有 6 辰之差，两者不可混用。
超辰
[编辑]木星恒星周期约 11.8622 年，非整 12 年，故约每 86 年出现一次超辰（岁星越过一辰），古历有相应处置。本模块按瞬时位置判定，不内置超辰校正，长期纪年推算需另行处理。
分野
[编辑]十二次各配一国：析木—燕、星纪—吴越、玄枵—齐、娵訾—卫、降娄—鲁、大梁—赵、实沈—晋、鹑首—秦、鹑火—周、鹑尾—楚、寿星—郑、大火—宋。
别名版本对照
[编辑]| 干支/辰 | 《尔雅》 | 《史记》 |
|---|---|---|
| 甲 | 阏逢 | 焉逢 |
| 乙 | 旃蒙 | 端蒙 |
| 寅 | 摄提格 | 摄提格 |
| 卯 | 单阏 | 单阏 |
| 巳 | 大荒落 | 大芒落 |
| 未 | 协洽 | 叶洽 |
| 酉 | 作噩 | 作鄂 |
| 戌 | 阉茂 | 淹茂 |
注意事项
[编辑]- 时区默认 UTC+8，跨时区请自行换算。
- 经说与今说结果可能相差 6 辰，引用时务必注明采用哪一体系。
track=shiji仅影响岁阳、岁阴别名用字，不影响太岁所在辰的判定。- 模块为自包含，不依赖
Module:SunXiu，可与太阳模块独立运作。