模組:SunXiu/doc
此頁面為 Module:SunXiu 的說明文件
 | 此頁面是Module:SunXiu的模組文件。 此頁面可能包含了模板的使用說明、分類和其他內容。 |
本模塊用於計算任意時刻太陽的精確位置，並將其映射到中國傳統天文體系（二十八宿、十二次）與中西黃道體系（西洋十二宮、IAU真實星座）。
概述
[編輯]時區默認 UTC+8：
- 太陽幾何位置：黃經、赤緯、赤經、日地距、均時差、視半徑等。
- 二十四節氣：以定氣法迭代求解交節時刻，輸出當前所處節氣區間、已過天數、距下一節氣天數。
- 黃道宮多體系對照：西洋回歸十二宮 / 西洋恆星十二宮 / IAU 真實星座（含蛇夫座）/ 中國十二次+十二辰 / 二十八宿日躔。
完整參數表
[編輯]太陽幾何位置
[編輯]| 字段 | 含義 | 單位 |
|---|---|---|
jd |
儒略日（UT） | 日 |
jd_tt |
儒略日（力學時 TT） | 日 |
T |
儒略世紀數（自 J2000.0 起） | 世紀 |
lon |
太陽真黃經（幾何，未含光行差與章動） | ° |
lon_app |
視黃經（含光行差 + 章動修正） | ° |
lat |
黃緯（恆為 0，保留字段） | ° |
ra |
赤經 | 小時 |
ra_deg |
赤經 | ° |
dec |
赤緯 | ° |
dist_au |
日地距離 | AU |
eq_time |
均時差 | 分 |
eps_true |
真黃赤交角 | ° |
radius_arcsec |
太陽視半徑 | ″ |
二十四節氣（定氣法）
[編輯]以春分黃經 0° 起，每 15° 一節氣，二分法迭代求解交節時刻。
| 字段 | 含義 |
|---|---|
prev_term |
上一節氣名 |
prev_term_jd |
上一節氣交節 JD |
prev_term_time |
上一節氣北京時間 |
cur_term |
當前所處節氣段名（如"寒露後"） |
days_after_term |
當前節氣後天數（浮點） |
days_after_term_hm |
格式化："第3天 04時12分" |
next_term |
下一節氣名 |
next_term_jd |
下一節氣 JD |
next_term_time |
下一節氣北京時間 |
days_to_next_term |
距下一節氣剩餘天數（浮點） |
term_lon |
當前段對應黃經基準（如寒露 = 195°） |
黃道宮體系
[編輯]西洋回歸黃道十二宮（Tropical，錨定春分點）
[編輯]| 字段 | 含義 |
|---|---|
trop_sign |
宮名（白羊宮/金牛宮/…/雙魚宮） |
trop_sign_cn |
中文宮名（同上，保留字段） |
trop_in_deg |
入本宮距度（0–30°） |
trop_days_to_next |
距下一宮天數 |
西洋恆星黃道（Sidereal，含歲差偏移）
[編輯]| 字段 | 含義 |
|---|---|
sidereal_sign |
恆星制宮名 |
sidereal_ayanamsa |
歲差修正量（°） |
sidereal_in_deg |
入宮距度（0–30°） |
IAU 實際黃道星座（含蛇夫座）
[編輯]| 字段 | 含義 |
|---|---|
iau_constellation |
真實星座（白羊座/…/蛇夫座/…） |
iau_in_deg |
入星座邊界距度 |
iau_note |
"宮≠星座"說明 |
中國十二次（自西向東等分，配十二辰）
[編輯]| 字段 | 含義 |
|---|---|
xing_ci |
星次名（星紀/玄枵/娵訾/降婁/大梁/實沈/鶉首/鶉火/鶉尾/壽星/大火/析木） |
chen |
十二辰（子丑寅卯辰巳午未申酉戌亥） |
xingci_in_deg |
入本次距度 |
十二次↔十二辰↔宿大致對應：
- 星紀(丑)·鬥牛｜玄枵(子)·女虛危｜娵訾(亥)·室壁｜降婁(戌)·奎婁｜大梁(酉)·胃昴畢｜實沈(申)·觜參｜鶉首(未)·井鬼｜鶉火(午)·柳星張｜鶉尾(巳)·翼軫｜壽星(辰)·角亢｜大火(卯)·氐房心｜析木(寅)·尾箕
中國二十八宿日躔
[編輯]| 字段 | 含義 |
|---|---|
sun_xiu |
太陽所在宿名 |
sun_xiu_in_deg |
入宿距度 |
sun_xiu_quji |
去極度（90° − 赤緯） |
sun_xiu_system |
所用宿度體系（huainan/dayan_ecl/dayan_equ/modern） |
sun_xiu_sysname |
宿度體系中文名 |
接口（公開函數）
[編輯]| 接口 | 說明 | 示例 |
|---|---|---|
p.get |
取任意單個字段值 | {{#invoke:SunXiu|get|param=sun_xiu}}
|
p.getJD |
取當前儒略日 | {{#invoke:SunXiu|getJD}}
|
p.infoBox |
完整信息框（6 區塊） | {{#invoke:SunXiu|infoBox|system=modern}}
|
p.short |
簡潔摘要（一行） | {{#invoke:SunXiu|short}}
|
p.solarTermTable |
指定年份 24 節氣時刻表 | {{#invoke:SunXiu|solarTermTable|year=2026}}
|
p.zodiac |
多體系黃道宮對照表 | {{#invoke:SunXiu|zodiac}}
|
調用參數
[編輯]所有接口均接受以下 frame.args 參數：
| 參數 | 含義 | 默認 |
|---|---|---|
year |
年份 | 當前年 |
month |
月份（1–12） | 當前月 |
day |
日期（1–31） | 當日 |
hour |
小時（UTC+8） | 12 |
system |
二十八宿宿度體系，可選值：huainan（淮南子距度）dayan_ecl（大衍曆黃道）dayan_equ（大衍曆赤道）modern（現代真黃道） |
huainan
|
示例
[編輯]- 太陽所在宿名：
{{#invoke:SunXiu|get|param=sun_xiu}}→ 畢 - 太陽視黃經：
{{#invoke:SunXiu|get|param=lon_app}}→ 231.92807 - 太陽赤緯：
{{#invoke:SunXiu|get|param=dec}}→ -18.24621 - 儒略日：
{{#invoke:SunXiu|getJD}}→ 2461358.7916667 - 距下一節氣天數（格式化）：
{{#invoke:SunXiu|get|param=days_after_term_hm}}→ 6天 21時02分 - 多體系對照：返回西洋宮 / 真實星座 / 十二次 / 宿的對照表。
{{#invoke:SunXiu|zodiac}} →
| 體系 | 名稱 | 入度 | 備註 |
|---|---|---|---|
| 回歸黃道宮 | 天蠍宮 | 21.93° | 春分點為0° |
| 恆星黃道宮 | 天秤座 | 28.93° | 歲差偏移 23.00° |
| IAU真實星座 | 天蠍座 | 21.93° | 註：IAU星座邊界非均勻，此為近似 |
| 中國十二次 | 大火（辰在卯） | 21.93° | 起於星紀 |
| 二十八宿日躔 | 畢 | 5.93° | 體系：《淮南子·天文訓》距度 |
- 指定參數：
{{#invoke:SunXiu|infoBox|year=2026|month=10|day=23|hour=20|system=modern}}→
模板
[編輯]基於 Module:SunXiu 計算當前或指定日期的太陽位置、二十八宿、節氣、黃道宮等信息。
參數
[編輯]year– 年份（數字），默認當前年month– 月份（1–12），默認當前月day– 日期（1–31），默認當日hour– 小時（0–23，UTC+8），默認12時system– 二十八宿體系，可選huainan（默認）、dayan_ecl、dayan_equ、modern
輸出內容
[編輯]- 浮動信息框：太陽所在的二十八宿、入宿距度、去極度、體系
- 幾何位置：黃經、赤緯、赤經、日地距、均時差、視半徑
- 節氣狀態：當前節氣區間、已過時長、下一節氣及時刻
- 回歸黃道宮、恆星黃道宮、IAU真實星座、中國十二次
- 可摺疊原始數據：JD、JD_TT、T、視黃經、赤緯、日地距、均時差、視半徑
相關模板
[編輯]完整信息框
{{SunXiuall}}
{{SunXiuall|year=2026|month=10|day=23|hour=12|system=huainan}}
當前節氣
{{SunJQ}}
太陽位置
{{SunXiuJJ}}
{{SunXiuJJ|year=2026|month=10|day=23|hour=12|system=modern}}
技術說明
[編輯]- 時區默認 UTC+8，若需其他時區請在調用前換算。
- "宮"≠"星座"：西洋十二宮為等分 30°，IAU 真實星座邊界不均等（且含蛇夫座），兩者不可混用。
- 十二次為等分體系，二十八宿不等分；跨宿/跨次邊界以太陽真黃經精確判定。
- 節氣時刻採用定氣法，與現行農曆節氣一致；與平氣法（固定 15.x 天）略有出入。
- 本模塊為自包含設計，不依賴外部數據模塊。
- 算法基於 Meeus 低階 VSOP 簡化公式，節氣採用定氣法（黃經每 15° 一節點）二分迭代求解。