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

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

版本：13\.3\.0
npm 元数据更新时间：2026-11-12T09:58:03.127Z
中文译文更新时间：2026-11-13T20:29:06.950Z
软件包许可：ISC

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

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

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

- 包体积（解压后）：664 kB，97 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：9 个
- peer 依赖：@equinor/fusion-framework-module-state ^2\.1\.0，@equinor/fusion-framework-module-bookmark ^4\.2\.0
- 首次发布：2022-08-22T05:13:00.028Z
- 最新版本发布：2026-11-12T09:58:02.751Z
- 近 30 天下载量：8498（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：329（近 12 个月 61 个）

## 中文简介

暂无中文简介

## 安装

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

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

## README

* * *

标题: "@equinor/suplic-framework-app" 说明:“Fusion框架应用基础包” 类别 : “ 应用 ” 标签 :

-   应用
-   核心项目
-   基础
-   模块
-   框架
-   类型标记

* * *

Fusion应用程序的配置和初始化层.

使用此软件包设置应用程序模块, 配置 HTTP 客户端, 集成 使用服务发现、启用书签和电线遥测设备——所有设备都有 单人 `configureModules` 电话.

> **大部分的聚合应用应该使用 `@equinor/fusion-framework-react-app` 换句话说.** 这个低级的软件包用于框架不可知或高级的情景.

## 文档

| 专题 | 说明 |
| --- | --- |
| [配置 HTTP 客户端](https://npmcn.com/package/%40equinor/fusion-framework-app/docs/http-clients.md) | 从 App 配置、服务发现和明确注册中命名客户端,加上分辨率优先级 |
| [启用书签](https://npmcn.com/package/%40equinor/fusion-framework-app/docs/bookmarks.md) | 通过注册书签模块 `enableBookmark` |
| [测试](https://npmcn.com/package/%40equinor/fusion-framework-app/docs/testing.md) | 这个 `/mock` 切入点 : `mockAppModules`, (中文(简体) ), `AppMockConfigurator`,以及 `enableAppManifestMock` |

## 安装

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

## 快速启动

```typescript
import type { AppModuleInitiator } from '@equinor/fusion-framework-app';
import { enableState } from '@equinor/fusion-framework-app/enable-state';

const configure: AppModuleInitiator = (configurator) => {
    enableState(configurator);
};
```

> \[叹息\] 状态管理模块是一个强大的工具,但是在您的应用中使用它时必须了解潜在的陷阱和局限性. 国家管理是全球性的,如果不仔细使用,可能导致出乎意料的行为.
> 
> **实例1:** 如果有多个依赖于同一状态的组件,更新一个组件中的状态会导致所有使用该状态的组件的重接,可能导致性能问题.
> 
> **实例2:** 用户打开了应用程序的多分页,每个分页都在修改相同的状态. 这会导致出乎意料的行为,因为一个标签中所做的修改会被反映到所有标签中. (类似于存储选定列的用户首选项)

#### 书签

[![](https://img.shields.io/github/package-json/v/equinor/fusion-framework?filename=packages%2Fmodules%2Fbookmark%2Fpackage.json&label=@equinor/fusion-framework-module-bookmark&style=for-the-badge)](https://github.com/equinor/fusion-framework/tree/main/packages/modules/bookmark)

_书签模块提供了保存和恢复应用程序状态的方法. 这对于在用户从应用程序中导航后返回应用程序时保存应用程序状态很有用._

```sh
# Install the bookmark module
pnpm add @equinor/fusion-framework-module-bookmark
```

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

// Create an initializer with custom configuration
const initialize = configureModules((configurator, { fusion, env }) => {
  // Register a named HTTP client
  configurator.configureHttpClient('myApi', {
    baseUri: 'https://api.example.com',
    defaultScopes: ['api://client-id/.default'],
  });
});

// Bootstrap the application
const modules = await initialize({ fusion, env });
```

## 关键概念

### 门户网站认证默认继承

`configureModules` 创建一个 `AppConfigurator` 登记册 `auth` 并行 `event` 财务报告和审定财务报表 `http` 在应用程序的配置调用运行前 。 它以 `fusion.modules` 作为母参考。 MSAL 然后通过兼容版本重新使用门户认证提供者 `createProxyProvider` 路径,共享已有的客户端和活账户而无需再登录. React App 靴子使用同样的路径.

普通主机应用程序不需要 `enableMSAL` 以使用角色 V2 。 登记册 `enableRoles` 通常情况下; 真实角色客户端在每次账户范围操作前读取继承的账户, 所以父程序 账户的变更和签出反映在以后的请求中。 无法使用的账户生成 `RequiredAccessRolesError`,而不是新的登录流.

故意自定义认证, 使用 `enableMSAL` 与 `builder.setProvider(customAuthProvider)`。 。 。 . 明确供应的供应商仍然具有权威性,即使在签字后也是如此。 一个赤裸的 `enableMSAL` 这里的调用是冗余的,仅客户端设置不会覆盖一个母端提供者 . 此默认注册独立于遥测, 不适用于光 `ModulesConfigurator` 鞋带。 见 [角色认证边界](https://npmcn.com/package/%40equinor/modules/roles/README.md#authentication-inheritance-and-custom-app-authentication)。 。 。 .

| 概念 | 说明 |
| --- | --- |
| `configureModules` | 用于创建应用程序模块的同步初始化器的工厂函数. |
| `AppConfigurator` | 内部配置器由 `configureModules`; 注册默认模块(`event`, (中文(简体) ), `http`, (中文(简体) ), `msal`)并读取端点配置. |
| `IAppConfigurator` | 配置器的公用接口,在打入配置回调时使用. |
| `AppModuleInitiator` | 接受回调签名 `configureModules` 用于用户提供的设置. |
| `AppEnv` | 环境描述符,包含应用程序的显示、配置和可选的碱名. |
| `enableBookmark` | 启用书签模块的辅助工具(从 `@equinor/fusion-framework-app/enable-bookmark`) (中文(简体) ). |
| `mockAppModules` | 运行真正的模块管道,防止用于测试的确定性假冒(进口自 `@equinor/fusion-framework-app/mock`) (中文(简体) ). |

## API 表面

### `configureModules(cb?)`

返回同步初始化器 `(args: { fusion, env }) => Promise<AppModulesInstance>`。 。 。 .

可选回调收到 `IAppConfigurator` 和合力/电弧, 允许您访问:

-   **`configurator.configureHttpClient(name, options)`** ——注册一个命名为HTTP的客户端,并有明确的基础URI和范围.
-   **`configurator.configureHttp(...)`** ——低级HTTP模块配置.
-   **`configurator.useFrameworkServiceClient(serviceName, options?)`** 注册客户端通过Fusion服务发现解决.
-   **`configurator.configureAppIdentification(options)`** 控制 `x-fusion-app*` 用于识别后端遥测的应用程序头. 见 [应用程序标识信头](https://npmcn.com/package/%40equinor/fusion-framework-app/docs/http-clients.md#app-identification-headers)。 。 。 .

### 子路径导出

| 导出路径 | 它提供的东西 |
| --- | --- |
| `@equinor/fusion-framework-app` | `configureModules`, (中文(简体) ), `AppConfigurator`, (中文(简体) ), `IAppConfigurator`,所有类型的别名 |
| `@equinor/fusion-framework-app/enable-bookmark` | `enableBookmark` 函数 |
| `@equinor/fusion-framework-app/mock` | `mockAppModules`, (中文(简体) ), `AppMockConfigurator`, (中文(简体) ), `enableAppManifestMock` |

## 配置 HTTP 客户端

这个 `AppConfigurator` 可以从多个来源注册命名的 HTTP 客户端 —— 应用程序配置终点、服务发现或明确登记 -- -- 然后在运行时找到一个 `framework.modules.http.createClient(name)`。 。 。 .

```ts
const initialize = configureModules((configurator) => {
  configurator.useFrameworkServiceClient('people');
});
```

见 [配置 HTTP 客户端](https://npmcn.com/package/%40equinor/fusion-framework-app/docs/http-clients.md) 自动登记 `app.config.ts`明确登记,并在客户时解决优先权问题 以多个位置配置.

## 启用书签

书签模块允许应用程序保存并恢复应用程序状态.

> **重要内容:** 导入 `enableBookmark` 从应用程序级软件包,而不是从 `@equinor/fusion-framework-module-bookmark` 直接说.

```ts
import { enableBookmark } from '@equinor/fusion-framework-app/enable-bookmark';

const initialize = configureModules((configurator) => {
  enableBookmark(configurator);
});
```

见 [启用书签](https://npmcn.com/package/%40equinor/fusion-framework-app/docs/bookmarks.md) 用于有效载荷生成器清理行为.

## 测试

从 `@equinor/fusion-framework-app/mock` 以运行一个应用程序的真实性 试验中的模块管道——实际 `event`编号 :`http`编号 :`msal` 模块,真实 `AppConfigurator` 配置管道,以及实际生命周期——只有 到达进程外的边框被确定性替换 伪造的 这个入场点不依赖Vitest或任何其他试跑者.

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

const manifest = { appKey: 'my-app', displayName: 'My App', description: 'My app', type: 'standalone' } as const;
const modules = await mockAppModules(undefined, { manifest });
```

见 [测试](https://npmcn.com/package/%40equinor/fusion-framework-app/docs/testing.md) 页:1 `AppMockConfigurator`, (中文(简体) ), `enableAppManifestMock`, (中文(简体) ), 并定制了被嘲笑的父母的服务发现.

## 类型

| 类型 | 目的 |
| --- | --- |
| `AppEnv` | 环境描述符( 明显、 配置、 底名、 道具) |
| `AppModuleInitiator` | 配置回调签名 `configureModules` |
| `AppModuleInit` | 全厂类型包装 `AppModuleInitiator` |
| `AppModuleInitArgs` | 将参数传递给返回的初始化器 |
| `AppRenderFn` | 将应用程序安装到 DOM 元素的渲染函数 |
| `AppManifest` | 应用程序显示元数据(再导出) |
| `AppConfig` | 特定环境配置(再出口) |
| `AppModules` | 默认应用模块的联盟(再出口) |
| `AppModulesInstance` | 初始化(再出口)后解决模块实例 |

## 进一步阅读

-   [组合框架文件](https://equinor.github.io/fusion-framework/)
-   [`@equinor/fusion-framework-react-app`](https://npmcn.com/package/%40equinor/react/app/) - 装有钩子和提供商的反应包装器

## 常见问题

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

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

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

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

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

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

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

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

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

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

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

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