Skip to content
頁內導覽

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>
  );
}

捲動至此處時載入可執行範例。

排盤參數 ​

參數型別說明
birthdaystring必填。出生日期,例如 '2000-8-16'。日期採用國曆或農曆,由 birthdayType 決定。
birthdayType'solar' | 'lunar'必填。國曆填 'solar',農曆填 'lunar'。
birthTimenumber必填。出生時辰索引,範圍為 0 至 12。例如 2 代表寅時,12 代表晚子時。
genderGenderName必填。繁體中文範例使用 '男' 或 '女'。
isLeapMonthboolean農曆出生日期是否在閏月,預設為 false。
fixLeapboolean排盤時是否調整閏月,預設為 true。詳見 astro.withOptions()。
langLanguage星盤和運限的輸出語言。明確指定時,優先於 options.language。
astroTypeAstroType星盤類型。'heaven' 是預設的天盤,'earth' 是地盤,'human' 是人盤。
optionsConfig目前星盤的排盤設定,例如 { yearDivide: 'exact' } 表示以立春為歲首分界。

如果出生資料來自表單,請在驗證通過後才顯示呼叫 Hook 的子元件。日期空白或無法解析時會略過排盤,原有結果可能會繼續顯示。其他無效輸入可能會使 iztro 擲出錯誤。詳見排盤設定與輸入驗證。

回傳值 ​

欄位說明
astrolabeFunctionalAstrolabe 執行個體。可以讀取十二宮、主星等資料,也可以呼叫執行個體的方法繼續查詢。
horoscopeFunctionalHoroscope 物件,包含大限、小限、流年、流月、流日和流時等結果。初始值按本地日期與時辰計算。
setHoroscope(date, hour?)更新運限查詢條件。date 接受國曆日期字串或 Date,hour 接受 0 至 12 的時辰索引。省略 hour 時,Hook 會依傳入日期的本地小時換算時辰。

setHoroscope 的回傳值為 void。請在後續渲染時讀取更新後的 horoscope。此方法只會更新運限查詢條件,出生資料仍由 Hook 的輸入參數決定。

GitHub 原始碼 · npm