# @bloomreach/navapp-communication 中文文档

规范地址：https://npmcn.com/package/%40bloomreach/navapp-communication/

版本：3\.5\.0
npm 元数据更新时间：2026-10-15T09:45:46.942Z
中文译文更新时间：2026-11-08T07:59:10.285Z
软件包许可：未声明

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

原始 npm 页面：https://www.npmjs.com/package/%40bloomreach/navapp-communication
原文对照：https://npmcn.com/package/%40bloomreach/navapp-communication/?lang=original

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

- 包体积（解压后）：126 kB，7 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：penpal ^4\.0\.0
- 首次发布：2019-05-08T09:31:43.377Z
- 最新版本发布：2026-10-15T09:45:46.719Z
- 近 30 天下载量：3088（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：77（近 12 个月 9 个）

## 中文简介

暂无中文简介

## 安装

```sh
npm install @bloomreach/navapp-communication
```

也可以使用：`pnpm add @bloomreach/navapp-communication`、`yarn add @bloomreach/navapp-communication`、`bun add @bloomreach/navapp-communication`

## README

# 导航通信

`@bloomreach/navapp-communication` bloomreach 导航应用软件库(导航)和 它的主机用来相互交谈的应用程序.

导航程序将每个应用程序装入自己的iframe,可能来自另一个来源. 这个图书馆设置了一个打字机, 基于承诺的API双向跨 Iframe 边界:

-   页:1 **父目录** (导航) 暴露一个 [`ParentApi`](https://npmcn.com/package/%40bloomreach/navapp-communication/src/lib/api.ts) 应用程序调用,例如更新浏览器 URL,显示口罩或关闭弹出;
-   每个 **儿童** (iframe中的应用)暴露于 [`ChildApi`](https://npmcn.com/package/%40bloomreach/navapp-communication/src/lib/api.ts) 纳瓦普呼叫,例如 导航,收集导航物品或登出.

盖下它用 [彭帕尔](https://github.com/Aaronius/penpal) (v4) 联合国 `postMessage` 握手和方法 打电话.

```
┌──────────────────────── navapp (parent) ────────────────────────┐
│  connectToChild({ iframe, methods: ParentApi }) → ChildApi       │
│                                                                  │
│   ┌──── iframe: CMS ─────┐        ┌──── iframe: popup app ────┐  │
│   │ connectToParent({    │        │ connectToParent({         │  │
│   │   methods: ChildApi  │        │   methods: ChildApi       │  │
│   │ }) → ParentApi       │        │ }) → ParentApi            │  │
│   └──────────────────────┘        └───────────────────────────┘  │
└──────────────────────────────────────────────────────────────────┘
```

孩子们从不直接交谈 当一个应用程序需要从另一个应用程序得到什么时(例如弹出) 请求 CMS 打开文档,它称为 `ParentApi` 方法 和 navapp 将呼叫转发给合适的孩子.

## 谁用

| 消费者 | 作用 |
| --- | --- |
| [`community/navigation-application`](https://npmcn.com/package/%40bloomreach/navigation-application) | 父: 执行 `ParentApi` 内 `ConnectionService` |
| CMS( 钱包) | 子 : 装入 UMD 捆绑和执行 `ChildApi` 内 `navapp-bridge.js` |
| [`community/channel-manager/ui`](https://npmcn.com/package/%40bloomreach/channel-manager/ui) | 儿童 |
| [`community/cms/frontend`](https://npmcn.com/package/%40bloomreach/cms/frontend) | 儿童 |
| [`enterprise/wpm/frontend/project-management`](https://npmcn.com/package/enterprise/wpm/frontend/project-management) | 儿童 |
| [`enterprise/ai-service/client/assistant-angular`](https://npmcn.com/package/enterprise/ai-service/client/assistant-angular) | 儿童(人数) |

每个消费者在自己的版本中标注 `package.json`,所以他们并不都使用相同的释放.

## 使用量

安装库及其对等依赖 :

```bash
npm install @bloomreach/navapp-communication penpal@^4
```

### 儿童申请

在应用程序启动时连接到父程序一次, 并保存返回 `ParentApi`数字 :

```ts
import { ChildApi, connectToParent, ParentApi } from '@bloomreach/navapp-communication';

const childApi: ChildApi = {
  getConfig: async () => ({ apiVersion: '3.3.0' }),
  navigate: async (location, triggeredBy) => router.navigate(location.path),
  beforeNavigation: async () => !hasUnsavedChanges(),
};

const parentApi: ParentApi = await connectToParent({
  // Must be the navapp's origin, or the connection is refused. window.location.origin only works when the
  // application is served from the same origin as the navapp; otherwise pass the navapp's origin explicitly.
  parentOrigin: window.location.origin,
  methods: childApi,
});

const { userSettings } = await parentApi.getConfig();
await parentApi.updateNavLocation({ path: 'documents/123', breadcrumbLabel: 'My document' });
```

全体 `ChildApi` 方法是可选的。 只执行您的应用程序支持的那些 .

### 在父( 导航)

```ts
import { connectToChild, ParentApi } from '@bloomreach/navapp-communication';

const childApi = await connectToChild({
  iframe,                         // the iframe element hosting the child
  methods: parentApi,             // the ParentApi implementation
  connectionTimeout: 30000,       // ms to wait for the handshake
  methodInvocationTimeout: 30000, // ms to wait for each child method call
});

const navItems = await childApi.getNavItems?.();
```

### 没有捆绑

该图书馆还作为UMD捆绑出版(U`dist/index.umd.js`登记全球 `window.brNavappCommunication`它期望 Penpal 首先作为全局加载 `Penpal`。这是CMS如何使用 这个.

## 知情的行为

-   **可选方法用可选的链条来称呼.** 连接的应用程序只会暴露它执行的方法 更古老的应用软件可能不知道更新的方法,所以称它们为 `api.someMethod?.()`。 。 。 .
-   **方法超时.** `connectToChild` 包住每个孩子的方法,以拒绝 `"<method> call timed out"` 之后 `methodInvocationTimeout` ms,或者5分钟 如果你没有设置一个. `beforeNavigation` 财务报告和审定财务报表 `openPicker` 从来没有 包裹, 因为他们等待用户回答对话框或选择项目 。 过 `0` 或关闭超时的负值.
-   **握手复会.** Penpal v4只发出一次握手,所以一个孩子在父母听话前就装入 永远不会连接. `connectToParent` 每秒重发一次握手,直到父母回复为止.
-   **版本检查.** `getVersion()` 返回库版本。 导航报告是 `ParentConfig.apiVersion`, (中文(简体) ), 儿童报告其实施的版本 `ChildConfig.apiVersion`。 。 。 .

## 向 API 添加方法

新能力通常会触及到库,导航和至少一个孩子:

1.  将方法添加到 `ParentApi` 和(或) `ChildApi` 内 [`src/lib/api.ts`](https://npmcn.com/package/%40bloomreach/navapp-communication/src/lib/api.ts),并附有医生的评论. 制作新方法 **选项** (单位:千美元)`myMethod?: ...`),因此针对更古老的版本所构建的应用程序仍然会编译并运行. 从同一文件中导出任何新类型 .
2.  在导航上执行 `ConnectionService` (单位:千美元)`getParentApiMethods`)并添加一个 spec.
3.  在儿童申请中执行或调用需要的,使用可选的链条.
4.  跳出库版(小于新可选方法),然后发布(参见 [释放](https://npmcn.com/package/%40bloomreach/navapp-communication/#readme-releasing),并更新 依赖每一个使用新类型的消费者.

TypeScript 消费者只在步骤4后看到新类型. 在那之前,他们的建筑失败 错误如 `Property 'myMethod' does not exist on type 'ParentApi'`。在发布前尝试修改,构建库并复制 `dist/*` 进入消费者 `node_modules/@bloomreach/navapp-communication/dist/`下一个 `npm ci` 还原它.

CMS 桥(`navapp-bridge.js`)是平版JavaScript和Penpal匹配方法的名称,因此不需要新的 库版本.

## 发展

此库的工具链比 Angular 应用程序要老' (参见仓库) `CLAUDE.md` 联 合 国 预期节点和npm版本.

```bash
npm ci                  # install dependencies
npm run build           # build dist/ (UMD, ES module and type definitions) with rollup
npm start               # rebuild on every change
npm run test:single-run # run the unit tests once
npm test                # run the tests in watch mode, with coverage
npm run lint            # lint src/
npm run docs            # generate the API docs with TypeDoc
```

`npm run build` 打印一系列 `(!) Plugin typescript` 关于警告 `node_modules/@types/node` 财务报告和审定财务报表 `undici-types`。它们来自这里使用的 TypeScript 版本, 它太老了, 无法分析最近的节点类型定义 测试工具带来。 它们是无害的: `created dist/index.js` 财务报告和审定财务报表 `created dist/index.d.ts`。 。 。 .

## 释放

没有CI的工作来出版这个图书馆。 释放是用手进行的:

1.  弹出 `version` 内 `package.json` (和 `package-lock.json`) (中文(简体) ).
2.  做测试吧 `npm publish` 从此目录. `prepack` 正在建设 `dist/` 先说 出版需要写 访问 `@bloomreach` npm 范围.
3.  在需要发布版本的消费者中更新版本,并刷新他们的锁文件.

## 常见问题

### 如何安装 @bloomreach/navapp-communication？

在项目目录运行 npm install @bloomreach/navapp-communication，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：penpal（^4\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @bloomreach/navapp-communication 支持 TypeScript 吗？

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

### @bloomreach/navapp-communication 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @bloomreach/navapp-communication 可以商用吗？

@bloomreach/navapp-communication 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @bloomreach/navapp-communication 的下载量有多少？

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

### @bloomreach/navapp-communication 还在维护吗？

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