配置和插件 ^2.3.0
歡迎使用iztro配置和插件功能。紫微斗數流派眾多，不同的流派的四化以及星曜亮度都會有些許差異，為了滿足不同流派的需求和功能的擴展，iztro在 v2.3.0 版本加入了全局配置和第三方插件功能。
提示
如果有讀者基於iztro開發了第三方插件開源庫，請 聯繫作者 將插件加入到文檔列表以便使用。
配置
可用的設定項目請參考 設定定義。若要設定全域預設值，請在呼叫排盤方法之前呼叫 astro.config()，範例如下：
import { astro } from 'iztro';
astro.config({
mutagens: { 庚: ['太陽', '武曲', '天同', '天相'] },
brightness: {
貪狼: ['旺', '旺', '旺', '旺', '旺', '旺', '旺', '旺', '旺', '旺', '旺', '旺'],
},
});執行上述程式碼後再呼叫排盤方法，指定的設定會與預設設定合併後套用。只需指定與預設值不同的項目。預設四化表請參考 十天干四化表，預設星曜亮度請參考 星曜亮度表。
除 mutagens 和 brightness 外，還可以透過以下選項調整排盤規則：
| 配置項 | 可選值 | 預設值 | 說明 |
|---|---|---|---|
yearDivide ^2.4.0 | normal | exact | normal | 年干支分界；normal 以農曆正月初一為界，exact 以立春為界 |
horoscopeDivide ^2.4.3 | normal | exact | normal | 運限使用的年、月干支分界 |
ageDivide ^2.4.5 | normal | birthday | normal | 小限虛歲分界；normal 只看自然年，birthday 以農曆生日為界 |
dayDivide ^2.5.2 | forward | current | forward | 晚子時歸屬；forward 歸入次日，current 歸入當日 |
algorithm ^2.5.0 | default | zhongzhou | default | 安星規則；default 為通行版本，zhongzhou 為中州派版本 |
注意
從 v2.6.2 開始，astro.config() 僅設定後續新建星盤的預設配置；withOptions({ config }) 僅覆蓋當前星盤，不再寫入全局預設配置。既有星盤及其運限、四化分析保留產生時的配置和語言。若舊程式依賴單次排盤修改全局配置，請改為明確呼叫 astro.config()。
getConfig() ^2.3.0
用途
取得目前已生效的全局配置。傳回的
^2.6.2 回傳值是獨立深拷貝，修改物件或其中的四化、亮度陣列不會改變函式庫配置。mutagens和brightness使用函式庫內部的規範化鍵名，適合用於偵錯或確認配置狀態。定義
tstype getConfig = () => { mutagens: Partial<Record<HeavenlyStemKey, StarKey[]>>; brightness: Partial<Record<StarKey, BrightnessKey[]>>; yearDivide: 'normal' | 'exact'; ageDivide: 'normal' | 'birthday'; dayDivide: 'current' | 'forward'; horoscopeDivide: 'normal' | 'exact'; algorithm: 'default' | 'zhongzhou'; };參數
無
傳回值
目前生效的配置物件
示例
tsimport { astro } from 'iztro'; astro.config({ algorithm: 'zhongzhou', ageDivide: 'birthday' }); const currentConfig = astro.getConfig();
resetConfig() ^2.6.2
恢復預設配置並清除所有自訂四化、亮度表；既有星盤不受影響。
type resetConfig = () => void;預設分界規則為 yearDivide: 'normal'、horoscopeDivide: 'normal'、ageDivide: 'normal'、dayDivide: 'forward'，安星方法為 algorithm: 'default'。本方法無參數、無回傳值，不重設已載入的插件。
const chart = astro.withOptions({
dateStr: '2000-8-16',
timeIndex: 3,
gender: '男',
config: { ageDivide: 'birthday' },
});
astro.resetConfig();
chart.horoscope('2026-3-1'); // 仍使用該星盤產生時的生日分界配置插件
iztro 的外掛是為星盤物件新增功能的函式，可依需求擴充功能。若使用 TypeScript 開發，請在繼承 FunctionalAstrolabe 的介面中宣告外掛方法。
介面宣告如下：
export interface IAstrolabe extends FunctionalAstrolabe {
myNewFunc: () => string;
majorStar: () => string;
}myNewFunc 和 majorStar 可依需求定義。介面中的方法可在同一個外掛函式中實作，也可分別在多個外掛函式中實作，範例如下：
// 創建一個插件函數
export function myTestPlugin(this: IAstrolabe): void {
// 實現插件應用邏輯
this.myNewFunc = () => {
return this.fiveElementsClass;
};
}
// 創建二個插件函數
export function myTestPlugin2(this: IAstrolabe): void {
// 實現插件應用邏輯
this.majorStar = () => {
let stars = this.palace('命宮')
?.majorStars.filter((item) => item.type === 'major' && !['祿存', '天馬'].includes(item.name))
.map((item) => item.name)
.join(',');
if (!stars) {
stars = this.palace('遷移')
?.majorStars.filter((item) => item.type === 'major' && !['祿存', '天馬'].includes(item.name))
.map((item) => item.name)
.join(',');
}
return stars ?? '';
};
}掛載插件的方法也非常簡單，只需要在引入 astro 以後執行 loadPlugin() 或者loadPlugins() 方法即可。兩種方式註冊的插件會套用到後續新建立的星盤實例。
import {astro} from iztro;
// 批量掛載插件
astro.loadPlugins([myTestPlugin， myTestPlugin2]);
// 逐個加載插件
astro.loadPlugin(myTestPlugin);
astro.loadPlugin(myTestPlugin2);如果只想為一個已經建立的星盤套用插件，可以呼叫該星盤實例的 use() 方法：
const astrolabe = astro.bySolar<IAstrolabe>('2023-10-18', 4, 'female');
astrolabe.use(myTestPlugin);
astrolabe.myNewFunc();提示
如果在typescript環境下使用插件時，需要指定泛型類型，這樣在編譯時才不會出現方法未定義的錯誤。比如我們要使用上述插件方法，需要：
const astrolabe = astro.bySolar<IAstrolabe>('2023-10-18', 4, 'female');
// 使用插件定義的方法
astrolabe.myNewFunc(); // 火六局
// 使用第二個插件方法
astrolabe.majorStar(); // 七殺