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

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

版本：8\.3\.0
npm 元数据更新时间：2026-11-12T09:57:33.911Z
中文译文更新时间：2026-11-13T20:16:51.966Z
软件包许可：ISC

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

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

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

- 包体积（解压后）：706 kB，127 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：7 个
- peer 依赖：@equinor/fusion-framework-module-telemetry ^8\.0\.0
- 首次发布：2022-01-14T12:21:29.212Z
- 最新版本发布：2026-11-12T09:57:33.677Z
- 近 30 天下载量：12176（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：249（近 12 个月 29 个）

## 中文简介

暂无中文简介

## 安装

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

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

## README

# @ equinor/ 组合框架- 模块- app

用于运行时加载,配置和管理Fusion应用程序的框架模块.

主要用于: **门户主机** 和其他需要动态发现、加载和在应用程序之间切换的框架发起者。 模块处理显示获取、构建解析度、配置加载、每个用户的应用程序设置,以及应用程序捆绑的脚本导入.

## 何时使用

-   您正在构建一个门户或外壳, 托管多个 Fusion 应用程序 .
-   您需要从 Fusion app 服务中获取应用程序清单和配置 .
-   您需要在运行时动态导入应用程序的 JavaScript 捆绑 .
-   您需要读取或写入每个用户的应用程序设置 .

> \[注\] 通过设计,这个模块只允许 **一个活动应用程序** 一次( e)`currentApp`) (中文(简体) ). 如果您需要多个并行应用实例,请使用部件模块取而代之 .

## 快速启动

启用框架配置符中的模块 :

```ts
import { enableAppModule } from '@equinor/fusion-framework-module-app';

export const configure = async (configurator: FrameworkConfigurator) => {
  enableAppModule(configurator);
};
```

一旦启用 `AppModuleProvider` 可在框架实例中找到:

```ts
const appProvider = framework.modules.app;

// Set the current application by key
appProvider.setCurrentApp('my-app');

// React to current app changes
appProvider.current$.subscribe((app) => {
  if (app) {
    console.log('Current app:', app.appKey);
  }
});
```

## 核心概念

### 应用程序

主运行时间入站. 提供下列方法:

-   **获取清单** – 说吧 – `getAppManifest(appKey)` 财务报告和审定财务报表 `getAppManifests()` 返回可观测流 `AppManifest` 对象.
-   **获取配置** – 说吧 – `getAppConfig(appKey)` 返回应用程序的环境和端点配置.
-   **管理设置** – 说吧 – `getAppSettings(appKey)` 财务报告和审定财务报表 `updateAppSettings(appKey, settings)` 每个用户读取和写入设置.
-   **设置/ 清除当前应用程序** – 说吧 – `setCurrentApp(appKey)` 创建一个 `App` 实例并发布 `current$`。 。 。 . `clearCurrentApp()` 处理当前应用程序 .

### 应用

代表一个装入的应用程序 。 通过被动状态机器管理显示、配置、设置和导入脚本模块的内部状态(`FlowSubject`) (中文(简体) ). 密钥可观察到 :

| 可观察 | 输出 |
| --- | --- |
| `manifest$` | `AppManifest` 解决后 |
| `config$` | `AppConfig` 解决后 |
| `settings$` | `AppSettings` (比较订阅) |
| `modules$` | 已导入 `AppScriptModule` |
| `instance$` | 已初始化 `AppModulesInstance` |
| `status$` | 一组在建行动类型 |

打电话 `app.initialize()` 将显示、配置和脚本平行地加载,并将其作为可观测的集合.

### 用户

与Fusion App服务API通信的低等HTTP客户端. 处理缓存( 通过 `Query`),响应解析(通过Zod schemas),以及将错误映射到打入错误类(`AppManifestError`, (中文(简体) ), `AppConfigError`, (中文(简体) ), `AppBuildError`, (中文(简体) ), `AppSettingsError`) (中文(简体) ).

### 应用程序

不可移动、被深冻的配置对象 `environment` (任意键值数据)和 `endpoints` (有 OAuth 范围的名称 URL). 使用 `config.getEndpoint('api')` 以获取特定终点.

### 应用程序配置器

模块初始化时使用的配置构建器 。 允许压倒默认的 HTTP 客户端和资产 URI :

```ts
enableAppModule(configurator, (builder) => {
  builder.setClient(async (args) => {
    const http = await args.requireInstance('http');
    return new AppClient(http.createClient('my-custom-apps'));
  });
  builder.setAssetUri('/custom-proxy');
});
```

## 活动

当 `EventModule` 可用时,应用程序模块会发送显示、配置、设置和脚本加载的生命周期事件。 主要活动包括:

-   `onCurrentAppChanged` - 当 `setCurrentApp` 或者说 `clearCurrentApp` 名为
-   `onAppManifestLoad` 编号 : `onAppManifestLoaded` 编号 : `onAppManifestFailure`
-   `onAppConfigLoad` 编号 : `onAppConfigLoaded` 编号 : `onAppConfigFailure`
-   `onAppSettingsLoad` 编号 : `onAppSettingsLoaded` 编号 : `onAppSettingsFailure`
-   `onAppScriptLoad` 编号 : `onAppScriptLoaded` 编号 : `onAppScriptFailure`
-   `onAppInitialize` 编号 : `onAppInitialized` 编号 : `onAppInitializeFailure`
-   `onAppDispose`

## 处理错误

所有 API 请求映射 HTTP 状态代码以输入错误类 :

| 错误类 | 当抛出时 |
| --- | --- |
| `AppManifestError` | 求解失败( 404, 401, 410) |
| `AppConfigError` | 配置获取失败 |
| `AppBuildError` | 构建元数据获取失败 |
| `AppSettingsError` | 设置获取或更新失败 |
| `AppScriptModuleError` | 脚本导入失败 |

每个错误包括: `type` 财产(`'not_found'`, (中文(简体) ), `'unauthorized'`, (中文(简体) ), `'deleted'`,或 `'unknown'`用于方案处理.

## 操作遥测

提供工具 `TelemetryConnectable` ,并通过 `telemetry.scope('app')`,有一个懒惰的工厂 倒背旧的定制供应商. 每个应用程序都拥有一个儿童范围;舞台观察员留在当地, 时间、安全身份和处置采用共享遥测方法.

当主机登记遥测时,每个应用程序都会报告一个 `fusion.app.<stage>.duration` 每个尝试阶段的结果: `load-manifest`, (中文(简体) ), `load-config`, (中文(简体) ), `load-settings`, (中文(简体) ), `update-settings`, (中文(简体) ), `import`, (中文(简体) ), `load`,以及 `unload` 当应用程序被替换或清除时. `load` 每个结果 `initialize()` 订阅:结果、错误或 `cancelled` 当召人先不订阅. 结果是 `success`, (中文(简体) ), `failure` (单位:千美元) 一个消毒 `.failure` 例外; 阶段故障带有静态原因, 如 `not-found`)或(或) `cancelled` (理由 `superseded`, (中文(简体) ), `unloaded`,或 `disposed` 当应用程序 模块被处理). 丢出记录失败的倒数 `unload`记录只携带 验证的 `appKey` 财务报告和审定财务报表 `appVersion`; 清单、配置、设置、 URL 和 错误消息从不导出 。 一个被替换的应用程序 停止载入报告, 即便同步模块被拆卸等待;其单独拥有 `unload` 当拆解结束时,测量结束。 排队阶段结果与 产生它们的请求, 不是一个新的请求 在同一阶段.

遥测在初始化后是相连的 从未等待过 所以装入结果, 错误和取消保持不变。 排除带有遥测适配器的这些记录 打开中继过滤器 `diagnostic.module === 'app'`。见 [操作遥测](https://npmcn.com/package/%40equinor/telemetry/docs/operational-telemetry.md)。 。 。 .

## 测试

从 `@equinor/fusion-framework-module-app/mock` 以服务一个应用程序的列表 并本地配置, 而不是联系应用程序服务 。 真实的 `AppClient` 仍然支持所有其他请求——其他应用密钥,标记请求,构建, 设置——如此指向 `setClient` 在不同的 http 客户端或服务中 发现登记册的工作保持不变.

```ts
import { MockAppClient } from '@equinor/fusion-framework-module-app/mock';

enableAppModule(configurator, (builder) => {
  builder.setClient(async ({ requireInstance }) => {
    const http = await requireInstance('http');
    return new MockAppClient(http.createClient('apps'), manifest, config);
  });
});
```

`getAppManifest` 仅本地解析 `manifest.appKey` 没有 `tag` 时间 都说吧. `getAppConfig` 决定 `manifest.appKey` 何时 `tag` 要么缺席 或等于仪表本身 `build.version` - 同样的标签 `App` 请求 当装入显示器的配置时,它已经解决了。 任何其他应用密钥, 标记,否则错误的请求会传递给真正的客户端.

> \[注\] `@equinor/fusion-framework-app/mock`是因为 `mockAppModules` 以此为基础 类,通常是测试应用程序的更简单的切入点—— 见它的 [测试](https://npmcn.com/package/app/docs/testing.md) 向导.

## 主要出口

| 导出 | 说明 |
| --- | --- |
| `enableAppModule` | 用框架配置器注册模块 |
| `AppModuleProvider` | 具有应用生命周期方法的运行时间提供者 |
| `AppClient` | 应用服务的低级 HTTP 客户端 |
| `AppConfigurator` | 模块设置配置构建器 |
| `AppConfig` | Immultable app 配置 (env + end points) 软件 |
| `App` 编号 : `IApp` | 反应状态的申请实例 |
| `AppModule` | 框架的模块定义 |
| `MockAppClient` | 测试双倍服务一个应用程序的显示和本地配置( T)`/mock`(中文(简体) ) |

## 常见问题

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

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

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

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

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

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

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

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

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

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

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

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