配置和插件 ^2.3.0
欢迎使用iztro配置和插件功能。紫微斗数流派众多,不同的流派的四化以及星曜亮度都会有些许差异,为了满足不同流派的需求和功能的扩展,iztro在 v2.3.0 版本加入了全局配置和第三方插件功能。
提示
如果有读者基于iztro开发了第三方插件开源库,请 联系作者 将插件加入到文档列表以便使用。
配置
关于配置的定义请参考 配置定义。全局配置十分简单,只需要在调用排盘方法之前调用 astro.config() 方法即可,具体代码如下:
import { astro } from 'iztro';
astro.config({
language: 'en-US',
mutagens: { 庚: ['太阳', '武曲', '天同', '天相'] },
brightness: {
贪狼: ['旺', '旺', '旺', '旺', '旺', '旺', '旺', '旺', '旺', '旺', '旺', '旺'],
},
});上述代码执行之后调用排盘方法时,将会把新的配置合并到默认配置中进行应用。换言之,在数据与默认配置相同的情况下,你并不需要重复在配置文件中设置。关于默认的四化表,请参考 十天干四化表。关于默认星曜亮度,请参考 星曜亮度表。
除 mutagens 和 brightness 外,还可以通过以下选项调整排盘规则:
| 配置项 | 可选值 | 默认值 | 说明 |
|---|---|---|---|
language ^2.6.5 | Language | zh-CN | 默认输出语言;显式 language 参数优先 |
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.4 起,统一处理晚子时换日:dayDivide: 'forward' 时,整张盘与后续运限按次日早子时计算,农历月份、年份和闰月状态会一并更新;current 时按当日早子时计算。
solarDate、time、timeRange 和 sign 保留原始公历生日、出生时段及星座;lunarDate、chineseDate 和 rawDates 反映用于排盘的日期。运限结果的 solarDate 也保留查询日期。
astro.config({ dayDivide: 'forward' });
const late = astro.bySolar('1996-8-13', 12, 'female');
const early = astro.bySolar('1996-8-14', 0, 'female');
console.log(late.lunarDate === early.lunarDate); // true
console.log(late.fiveElementsClass === early.fiveElementsClass); // true注意
从 v2.6.2 开始,astro.config() 仅设置后续新建星盘的默认配置;withOptions({ config }) 仅覆盖当前星盘,不再写入全局默认配置。已有星盘及其运限、四化分析保留生成时的配置和语言。旧代码若依赖单次排盘修改全局配置,请改为显式调用 astro.config()。
setLanguage() ^2.6.5
使用 astro.config({ language: 'en-US' }) 设置后续排盘、日期辅助方法及独立工具函数的默认输出语言,初始为 zh-CN。withOptions({ config: { language } }) 仅覆盖当前星盘;显式 language 参数优先。单次调用不修改全局默认值,已有星盘保留生成时的语言。
astro.setLanguage(language) 与 astro.config({ language }) 设置同一份全局语言,保留此入口以兼容已有调用。支持 zh-CN、zh-TW、en-US、ja-JP、ko-KR 和 vi-VN;非法语言会抛出错误并保留原设置。
type setLanguage = (language: Language) => void;astro.getConfig().language 返回当前配置的语言;astro.resetConfig() 会将全局语言恢复为 zh-CN,已有星盘及后续查询不受影响。
import { astro, util } from 'iztro';
astro.config({ language: 'en-US' });
console.log(astro.getConfig().language); // en-US
console.log(astro.getLanguage()); // en-US
console.log(util.getMutagensByHeavenlyStem('geng'));
// ['sun', 'warrior', 'moon', 'fortunate']
astro.resetConfig();getLanguage() ^2.6.5
获取当前生效的语言:在星盘方法或插件内返回该星盘生成时的语言,在计算上下文之外返回全局语言。
type getLanguage = () => Language;getConfig() ^2.3.0
用途
获取当前已生效的全局配置。返回的
^2.6.2 返回值是独立深拷贝,修改对象或其中的四化、亮度数组不会改变库的配置。mutagens和brightness使用库内部的规范化键名,适合用于调试或确认配置状态。定义
tstype getConfig = () => { language: Language; 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
恢复默认配置,并清除全部自定义四化、亮度表;已有星盘不受影响。
astro.getConfig().language 返回当前配置的语言;astro.resetConfig() 会将全局语言恢复为 zh-CN,已有星盘及后续查询不受影响。
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(); // 七杀