导航通信

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

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

• 页:1 父目录 (导航) 暴露一个 ParentApi 应用程序调用,例如更新浏览器 URL,显示口罩或关闭弹出;
• 每个 儿童 (iframe中的应用)暴露于 ChildApi 纳瓦普呼叫,例如 导航,收集导航物品或登出.

盖下它用 彭帕尔 (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 将呼叫转发给合适的孩子.

谁用

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

使用量

安装库及其对等依赖 :

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

儿童申请

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

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 方法是可选的。 只执行您的应用程序支持的那些 .

在父( 导航)

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捆绑出版(Udist/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,并附有医生的评论. 制作新方法 选项 (单位:千美元)myMethod?: ...),因此针对更古老的版本所构建的应用程序仍然会编译并运行. 从同一文件中导出任何新类型 .
2. 在导航上执行 ConnectionService (单位:千美元)getParentApiMethods)并添加一个 spec.
3. 在儿童申请中执行或调用需要的,使用可选的链条.
4. 跳出库版(小于新可选方法),然后发布(参见 释放,并更新 依赖每一个使用新类型的消费者.

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版本.

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. 在需要发布版本的消费者中更新版本,并刷新他们的锁文件.