模組: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，可與太陽模組獨立運作。