iztro-hook
iztro-hook 將 iztro 的排盤與運限計算封裝為 React Hook。透過 useIztro 取得資料後,可以自行設計星盤、表格或篩選介面。如需直接嵌入完整的互動星盤,可以使用 react-iztro。在 React 以外的環境,也可以直接使用 iztro。
安裝
sh
npm install iztro iztro-hook以下範例與參數以 iztro-hook 1.3.5 和 iztro 2.6.5 為基準。
取得星盤與運限
請在 React 函式元件或自訂 Hook 的最上層呼叫 useIztro。第一次渲染時,astrolabe 和 horoscope 都可能是 undefined,請在顯示結果前確認資料已產生。
tsx
import React from 'react';
import { useIztro } from 'iztro-hook';
export default function App() {
const { astrolabe, horoscope, setHoroscope } = useIztro({
birthday: '2000-8-16',
birthdayType: 'solar',
birthTime: 2,
gender: '女',
lang: 'zh-TW',
});
if (!astrolabe || !horoscope) {
return <p>正在產生星盤…</p>;
}
return (
<section>
<p>出生農曆日期:{astrolabe.lunarDate}</p>
<p>運限查詢日期:{horoscope.solarDate}</p>
<p>流年干支:{horoscope.yearly.heavenlyStem}{horoscope.yearly.earthlyBranch}</p>
<button type="button" onClick={() => setHoroscope('2025-10-19', 2)}>
查看 2025 年 10 月 19 日寅時的運限
</button>
</section>
);
}捲動至此處時載入可執行範例。
排盤參數
| 參數 | 型別 | 說明 |
|---|---|---|
birthday | string | 必填。出生日期,例如 '2000-8-16'。日期採用國曆或農曆,由 birthdayType 決定。 |
birthdayType | 'solar' | 'lunar' | 必填。國曆填 'solar',農曆填 'lunar'。 |
birthTime | number | 必填。出生時辰索引,範圍為 0 至 12。例如 2 代表寅時,12 代表晚子時。 |
gender | GenderName | 必填。繁體中文範例使用 '男' 或 '女'。 |
isLeapMonth | boolean | 農曆出生日期是否在閏月,預設為 false。 |
fixLeap | boolean | 排盤時是否調整閏月,預設為 true。詳見 astro.withOptions()。 |
lang | Language | 星盤和運限的輸出語言。明確指定時,優先於 options.language。 |
astroType | AstroType | 星盤類型。'heaven' 是預設的天盤,'earth' 是地盤,'human' 是人盤。 |
options | Config | 目前星盤的排盤設定,例如 { yearDivide: 'exact' } 表示以立春為歲首分界。 |
如果出生資料來自表單,請在驗證通過後才顯示呼叫 Hook 的子元件。日期空白或無法解析時會略過排盤,原有結果可能會繼續顯示。其他無效輸入可能會使 iztro 擲出錯誤。詳見排盤設定與輸入驗證。
回傳值
| 欄位 | 說明 |
|---|---|
astrolabe | FunctionalAstrolabe 執行個體。可以讀取十二宮、主星等資料,也可以呼叫執行個體的方法繼續查詢。 |
horoscope | FunctionalHoroscope 物件,包含大限、小限、流年、流月、流日和流時等結果。初始值按本地日期與時辰計算。 |
setHoroscope(date, hour?) | 更新運限查詢條件。date 接受國曆日期字串或 Date,hour 接受 0 至 12 的時辰索引。省略 hour 時,Hook 會依傳入日期的本地小時換算時辰。 |
setHoroscope 的回傳值為 void。請在後續渲染時讀取更新後的 horoscope。此方法只會更新運限查詢條件,出生資料仍由 Hook 的輸入參數決定。