# @equinor/fusion-framework-module 中文文档

规范地址：https://npmcn.com/package/%40equinor/fusion-framework-module/

版本：6\.2\.0
npm 元数据更新时间：2026-11-12T09:54:27.362Z
中文译文更新时间：2026-11-13T20:08:30.062Z
软件包许可：ISC

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40equinor/fusion-framework-module
原文对照：https://npmcn.com/package/%40equinor/fusion-framework-module/?lang=original
源码仓库：https://github.com/equinor/fusion-framework

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：416 kB，115 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：2 个
- peer 依赖：@types/semver ^7\.0\.0
- 首次发布：2022-01-14T12:18:11.926Z
- 最新版本发布：2026-11-12T09:54:26.926Z
- 近 30 天下载量：16770（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：136（近 12 个月 17 个）

## 中文简介

暂无中文简介

## 安装

```sh
npm install @equinor/fusion-framework-module
```

也可以使用：`pnpm add @equinor/fusion-framework-module`、`yarn add @equinor/fusion-framework-module`、`bun add @equinor/fusion-framework-module`

## README

# @ equinor/ 组合框架- 模块

融合框架核心模块系统. 这个软件包定义了每个Fusion框架模块所依赖的合同,基础类和管弦逻辑.

使用此软件包 **正在编写新模块** 或者需要了解模块生命周期是如何运作的。 应用程序开发人员通常通过更高层次的软件包,例如 `@equinor/fusion-framework-react`。 。 。 .

## 关键概念

### 模块

A 类 `Module` 是宣告名称、可选配置厂、 `initialize` 方法,以及可选的生命周期钩(`postConfigure`, (中文(简体) ), `postInitialize`, (中文(简体) ), `dispose`) (中文(简体) ). 模块是Fusion应用程序的构件.

### 模块配置器

`ModulesConfigurator` 协调整个模块生命周期:

1.  **配置** - 每个模块的 `configure()` 工厂创建一个配置构建器; 注册回调使其变异; `postConfigure()` 钩而跑.
2.  **初始化** - 模块同时初始化;跨模块依赖性通过 `requireInstance()`。 。 。 .
3.  **初始化后** – 说吧 – `postInitialize()` 钩子和 `onInitialized` 调用运行.
4.  **插件** – 注册插件在每个模块准备好后连接主机级副作用.

结果是密封 `ModulesInstance` 其属性名称与模块密钥相匹配,其值为初始化提供者.

### Basefig 构建器

用于构建模块配置的抽象类声明. 子类暴露出打入的设置方法(例如. `setBaseUrl`用于注册回调。 在初始化过程中,框架收集了所有已注册的回调,解析,并将结果合并为一个配置对象.

### BaseModule 创建器

模块提供者摘要基础类(运行时实例由 `initialize()`) (中文(简体) ). 它管理着一个 `Subscription` 自动拆卸的容器 `SemanticVersion` 用于兼容性检查.

## 文档

| 专题 | 说明 |
| --- | --- |
| [概念](https://npmcn.com/package/%40equinor/fusion-framework-module/docs/concepts.md) | 模块系统概览、作用和精神模式 |
| [生命周期](https://npmcn.com/package/%40equinor/fusion-framework-module/docs/lifecycle.md) | 配置-初始化-初始化后-处置相序 |
| [配置](https://npmcn.com/package/%40equinor/fusion-framework-module/docs/configuration.md) | 如何注册模块和使用 `addConfig` 编号 : `configure` |
| [跨部门依赖](https://npmcn.com/package/%40equinor/fusion-framework-module/docs/cross-module-deps.md) | `requireInstance` 模块间依赖关系模式 |
| [插件](https://npmcn.com/package/%40equinor/fusion-framework-module/docs/plugins.md) | `registerPlugin`, (中文(简体) ), `createPlugin`,插件拆卸,以及主机级副作用 |
| [活动](https://npmcn.com/package/%40equinor/fusion-framework-module/docs/events.md) | `event$` 观察和事件命名公约 |
| [撰写模块](https://npmcn.com/package/%40equinor/fusion-framework-module/docs/authoring-modules.md) | 创建自定义模块的分步指南 |
| [常见错误](https://npmcn.com/package/%40equinor/fusion-framework-module/docs/common-mistakes.md) | FAQ 式陷阱和如何避免它们 |

## 安装

```sh
pnpm add @equinor/fusion-framework-module
```

## 快速启动——定义模块

```typescript
import {
  type Module,
  BaseConfigBuilder,
  type ConfigBuilderCallback,
} from '@equinor/fusion-framework-module';
import { BaseModuleProvider } from '@equinor/fusion-framework-module/provider';

// 1. Define the configuration shape
interface GreeterConfig {
  greeting: string;
}

// 2. Create a config builder
class GreeterConfigurator extends BaseConfigBuilder<GreeterConfig> {
  setGreeting(cb: ConfigBuilderCallback<string>) {
    this._set('greeting', cb);
  }
}

// 3. Create a provider
class GreeterProvider extends BaseModuleProvider<GreeterConfig> {
  #config: GreeterConfig;

  greet(name: string): string {
    return `${this.#config.greeting}, ${name}!`;
  }

  constructor(args: { version: string; config: GreeterConfig }) {
    super(args);
    this.#config = args.config;
  }
}

// 4. Define the module
export const greeterModule: Module<'greeter', GreeterProvider, GreeterConfigurator> = {
  name: 'greeter',
  configure: () => new GreeterConfigurator(),
  initialize: async ({ config }) => {
    const resolved = await config.createConfigAsync({
      config: {},
      hasModule: () => false,
      requireInstance: () => Promise.reject('no modules'),
    });
    return new GreeterProvider({ version: '1.0.0', config: resolved });
  },
};
```

## 出口

### 主要入口点`@equinor/fusion-framework-module`(中文(简体) )

| 导出 | 仁爱 | 说明 |
| --- | --- | --- |
| `Module` | 类型 | 描述模块结构和生命周期钩的界面 |
| `ModulesConfigurator` | 类 | 管弦乐配置 → 初始化 → 插件 → 处理一组模块 |
| `IModulesConfigurator` | 接口 | 模块配置器的公共合同 |
| `IModuleConfigurator` | 接口 | 使用生命周期钩注册单一模块的说明 |
| `BaseConfigBuilder` | 类 | 有点-路径瞄准和可观测管线的抽象配置构建器 |
| `ConfigBuilderCallback` | 类型 | 配置构建器设置所用的召回签名 |
| `ConfigBuilderCallbackArgs` | 类型 | 参数传递给配置构建器的回调 |
| `ModuleConfigBuilder` | 类 | _折旧_ - 使用 `BaseConfigBuilder` 换成 |
| `initializeModules` | 函数 | 方便包装 `configurator.initialize()` |
| `SemanticVersion` | 类 | 扩展 `SemVer` 带有 `satisfies()` 方法 |
| `ModuleConsoleLogger` | 类 | 模块名称格式化的样式控制台日志 |
| `IModuleConsoleLogger` | 接口 | 锁定接口 `formatModuleName` |
| `DotPath`, (中文(简体) ), `DotPathType`, (中文(简体) ), `DotPathUnion` | 类型 | 递归点标记路径公用事业 |

### 配置子路径( S)`@equinor/fusion-framework-module/configurator`(中文(简体) )

| 导出 | 仁爱 | 说明 |
| --- | --- | --- |
| `ModuleConfiguratorEventBaseName` | 针头 | 共享 `ModuleConfigurator` 配置器生命周期事件名称的基段 |
| `ModuleConfiguratorEventName` | 对象 | 地图 `ModuleConfigurator.{name}.{state}` 用于过滤的事件名称 `event$` 没有硬码字符串 |

### 子路径( E)`@equinor/fusion-framework-module/plugins`(中文(简体) )

| 导出 | 仁爱 | 说明 |
| --- | --- | --- |
| `createPlugin` | 函数 | 为稳定的生命周期诊断创建一个命名的插件召回 |
| `FrameworkPluginArgs` | 类型 | 传递给内置插件调用参数:初始化模块和可选参考 |
| `FrameworkPluginCallback` | 类型 | 接受回电 `IModulesConfigurator.registerPlugin` |
| `FrameworkPluginTeardown` | 类型 | 由插件返回的清理回调或可支配对象 |
| `FrameworkPluginRegistration` | 类型 | 插件返回类型: 拆卸或 `undefined` |
| `FrameworkPlugin` | 接口 | 命名的插件调用返回 `createPlugin` |
| `FrameworkPluginInitializer` | 类型 | 开发者使用的回调签名 `createPlugin` |

### 提供子路径`@equinor/fusion-framework-module/provider`(中文(简体) )

| 导出 | 仁爱 | 说明 |
| --- | --- | --- |
| `IModuleProvider` | 接口 | 合同每个模块提供者必须满足 |
| `BaseModuleProvider` | 类 | 带有版本、订阅管理和处理的文摘基础 |
| `BaseModuleProviderCtorArgs` | 类型 | 构造参数 `BaseModuleProvider` |

## 模块周期

```
┌─────────────────────────────────────────────────────┐
│                  ModulesConfigurator                 │
├──────────┬──────────────────────────┬────────────────┤
│ Phase    │ Module Hook              │ Consumer Hook  │
├──────────┼──────────────────────────┼────────────────┤
│ Configure│ module.configure()       │ addConfig()    │
│          │ module.postConfigure()   │ onConfigured() │
├──────────┼──────────────────────────┼────────────────┤
│ Init     │ module.initialize()      │                │
│          │ module.postInitialize()  │ onInitialized()│
├──────────┼──────────────────────────┼────────────────┤
│ Plugin   │                          │ registerPlugin │
├──────────┼──────────────────────────┼────────────────┤
│ Dispose  │ module.dispose()         │ instance.      │
│          │                          │  dispose()     │
└──────────┴──────────────────────────┴────────────────┘
```

### 有需要的跨模块依赖性

模块同时初始化 。 使用 `requireInstance(name, timeout?)` 内部 `initialize` 等待依赖:

```typescript
initialize: async ({ config, requireInstance, hasModule }) => {
  // Wait for the event module (with optional timeout in ms)
  const event = await requireInstance('event', 5000);
  return new MyProvider(config, event);
},
```

`requireInstance` 返回当请求的模块完成初始化时解析的许诺。 如果模块没有注册,承诺会拒绝.

### 启动和完整模块映射

`postInitialize` 运行后 **全部** 模块已初始化。 它收到满分 `modules` 地图,使它成为跨模块接线的正确位置,这取决于每个模块是否准备好:

```typescript
postInitialize: async ({ instance, modules }) => {
  // All modules are available here
  modules.event.addEventListener('onContextChanged', (e) => {
    instance.handleContextChange(e.detail);
  });
},
```

`configure` 财务报告和审定财务报表 `initialize` 是两个需要的钩. `postConfigure`, (中文(简体) ), `postInitialize`,以及 `dispose` 是可选的.

### 插件和主机级副作用

使用 `registerPlugin` 用于在制作前需要完整的模块实例的应用程序自有接线。 插件运行后 `postInitialize` 财务报告和审定财务报表 `onInitialized`,但在 `initialize()` 决定。 返回已撕毁的回调, 以清理订阅、 全球收听器、 计时器或处理时的遥测绑定 .

```typescript
import { createPlugin } from '@equinor/fusion-framework-module/plugins';

const contextTelemetryPlugin = createPlugin<[typeof eventModule, typeof telemetryModule]>(
  'contextTelemetry',
  (modules) => modules.event.addEventListener('context:changed', (event) => {
    modules.telemetry.track('context.changed', event.detail);
  }),
);

configurator.registerPlugin(contextTelemetryPlugin);
```

见 [插件](https://npmcn.com/package/%40equinor/fusion-framework-module/docs/plugins.md) 用于拆解规则、失败行为和API参考.

事件在 `configurator.event$` 用于遥测和调试的整个生命周期.

## 相关软件包

-   `@equinor/fusion-framework-react` - 消费模块的反应装订和钩子
-   `@equinor/fusion-framework-module-http` – HTTP 客户端模块基于此系统
-   `@equinor/fusion-framework-module-service-discovery` - 服务发现模块

## 常见问题

### 如何安装 @equinor/fusion-framework-module？

在项目目录运行 npm install @equinor/fusion-framework-module，或使用 pnpm add / yarn add / bun add。

### @equinor/fusion-framework-module 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @equinor/fusion-framework-module 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @equinor/fusion-framework-module 可以商用吗？

@equinor/fusion-framework-module 使用 ISC 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @equinor/fusion-framework-module 的下载量有多少？

根据 npm 官方下载统计，@equinor/fusion-framework-module 在 2026/10/14 – 2026/11/12 这 30 天内被下载 16,770 次，日均约 559 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @equinor/fusion-framework-module 还在维护吗？

最新版本 6\.2\.0 发布于 2026/11/12（1 天前）；至今共发布 136 个版本，其中过去 12 个月发布了 17 个；首次发布于 2022/01/14。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。