Skip to content
页内导航

配置和插件 ^2.3.0 ​

欢迎使用iztro配置和插件功能。紫微斗数流派众多,不同的流派的四化以及星曜亮度都会有些许差异,为了满足不同流派的需求和功能的扩展,iztro在 v2.3.0 版本加入了全局配置和第三方插件功能。

提示

如果有读者基于iztro开发了第三方插件开源库,请 联系作者 将插件加入到文档列表以便使用。

配置 ​

关于配置的定义请参考 配置定义。全局配置十分简单,只需要在调用排盘方法之前调用 astro.config() 方法即可,具体代码如下:

ts
import { astro } from 'iztro';

astro.config({
  language: 'en-US',
  mutagens: { 庚: ['太阳', '武曲', '天同', '天相'] },
  brightness: {
    贪狼: ['旺', '旺', '旺', '旺', '旺', '旺', '旺', '旺', '旺', '旺', '旺', '旺'],
  },
});

上述代码执行之后调用排盘方法时,将会把新的配置合并到默认配置中进行应用。换言之,在数据与默认配置相同的情况下,你并不需要重复在配置文件中设置。关于默认的四化表,请参考 十天干四化表。关于默认星曜亮度,请参考 星曜亮度表。

除 mutagens 和 brightness 外,还可以通过以下选项调整排盘规则:

配置项可选值默认值说明
language ^2.6.5Languagezh-CN默认输出语言;显式 language 参数优先
yearDivide ^2.4.0normal | exactnormal年干支分界;normal 以农历正月初一为界,exact 以立春为界
horoscopeDivide ^2.4.3normal | exactnormal运限使用的年、月干支分界
ageDivide ^2.4.5normal | birthdaynormal虚岁分界,影响大限与小限;normal 以农历正月初一为界,birthday 按农历生日判断
dayDivide ^2.5.2forward | currentforward晚子时归属;forward 归入次日,current 归入当日
algorithm ^2.5.0default | zhongzhoudefault安星规则;default 为通行版本,zhongzhou 为中州派版本

虚岁的计算公式、农历生日分界及大限宫位索引示例见 虚岁与宫位索引。

自 v2.6.4 起,统一处理晚子时换日:dayDivide: 'forward' 时,整张盘与后续运限按次日早子时计算,农历月份、年份和闰月状态会一并更新;current 时按当日早子时计算。

solarDate、time、timeRange 和 sign 保留原始公历生日、出生时段及星座;lunarDate、chineseDate 和 rawDates 反映用于排盘的日期。运限结果的 solarDate 也保留查询日期。

ts
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;非法语言会抛出错误并保留原设置。

ts
type setLanguage = (language: Language) => void;

astro.getConfig().language 返回当前配置的语言;astro.resetConfig() 会将全局语言恢复为 zh-CN,已有星盘及后续查询不受影响。

ts
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 ​

获取当前生效的语言:在星盘方法或插件内返回该星盘生成时的语言,在计算上下文之外返回全局语言。

ts
type getLanguage = () => Language;

getConfig() ^2.3.0 ​

  • 用途

    获取当前已生效的全局配置。返回的 mutagens 和 brightness 使用库内部的规范化键名,适合用于调试或确认配置状态。

    ^2.6.2 返回值是独立深拷贝,修改对象或其中的四化、亮度数组不会改变库的配置。
  • 定义

    ts
    type 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';
    };
  • 参数

    无

  • 返回值

    当前生效的配置对象

  • 示例

    ts
    import { astro } from 'iztro';
    
    astro.config({ algorithm: 'zhongzhou', ageDivide: 'birthday' });
    
    const currentConfig = astro.getConfig();

resetConfig() ^2.6.2 ​

恢复默认配置,并清除全部自定义四化、亮度表;已有星盘不受影响。

astro.getConfig().language 返回当前配置的语言;astro.resetConfig() 会将全局语言恢复为 zh-CN,已有星盘及后续查询不受影响。

ts
type resetConfig = () => void;

默认分界规则为 yearDivide: 'normal'、horoscopeDivide: 'normal'、ageDivide: 'normal'、dayDivide: 'forward',安星方法为 algorithm: 'default'。本方法无参数、无返回值,不重置已加载的插件。

ts
const chart = astro.withOptions({
  dateStr: '2000-8-16',
  timeIndex: 3,
  gender: '男',
  config: { ageDivide: 'birthday' },
});
astro.resetConfig();
chart.horoscope('2026-3-1'); // 仍使用该星盘生成时的生日分界配置

插件 ​

iztro的插件就是一个函数,这个函数会挂载到星盘对象上。你可以根据自己的需求扩展功能。假如你是在typescript环境下开发,你需要将插件方法声明到接口中,而该接口需要继承自 FunctionalAstrolabe。

接口声明如下:

ts
export interface IAstrolabe extends FunctionalAstrolabe {
  myNewFunc: () => string;
  majorStar: () => string;
}

上述 myNewFunc 和 majorStar 方法可以根据你自己的需求进行定义。上述接口内的方法你可以在一个插件方法内实现,也可以在多个插件方法内实现。实现方法如下:

ts
// 创建一个插件函数
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() 方法即可。两种方式注册的插件会应用到后续新创建的星盘实例。

ts
import {astro} from iztro;

// 批量挂载插件
astro.loadPlugins([myTestPlugin, myTestPlugin2]);

// 逐个加载插件
astro.loadPlugin(myTestPlugin);
astro.loadPlugin(myTestPlugin2);

如果只想为一个已经创建的星盘应用插件,可以调用该星盘实例的 use() 方法:

ts
const astrolabe = astro.bySolar<IAstrolabe>('2023-10-18', 4, 'female');

astrolabe.use(myTestPlugin);
astrolabe.myNewFunc();

提示

如果在typescript环境下使用插件时,需要指定泛型类型,这样在编译时才不会出现方法未定义的错误。比如我们要使用上述插件方法,需要:

ts
const astrolabe = astro.bySolar<IAstrolabe>('2023-10-18', 4, 'female');

 // 使用插件定义的方法
 astrolabe.myNewFunc();   // 火六局

 // 使用第二个插件方法
 astrolabe.majorStar();   // 七杀