# @assembly-js/app-bridge 中文文档

规范地址：https://npmcn.com/package/%40assembly-js/app-bridge/

版本：2\.1\.0
npm 元数据更新时间：2026-10-29T13:24:59.581Z
中文译文更新时间：2026-11-07T00:15:01.385Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40assembly-js/app-bridge
原文对照：https://npmcn.com/package/%40assembly-js/app-bridge/?lang=original

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

- 包体积（解压后）：238 kB，23 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2026-01-29T00:27:31.983Z
- 最新版本发布：2026-10-29T13:24:58.924Z
- 近 30 天下载量：9259（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：12（近 12 个月 12 个）

## 中文简介

用于自定义应用程序和Copilot母应用程序之间Message后通信的帮助器功能

## 安装

```sh
npm install @assembly-js/app-bridge
```

也可以使用：`pnpm add @assembly-js/app-bridge`、`yarn add @assembly-js/app-bridge`、`bun add @assembly-js/app-bridge`

## README

# @ 组装- js/ app- bridge

辅助器功能用于自定义应用程序(嵌入于iframes)和Copilot母应用程序之间的Message后通信.

## 安装

### npm/ yarn( 亚伦)

```bash
npm install @assembly-js/app-bridge
# or
yarn add @assembly-js/app-bridge
```

## 使用量

### npm 使用量

```typescript
import { AssemblyBridge } from "@assembly-js/app-bridge";

// Set breadcrumbs
AssemblyBridge.header.setBreadcrumbs([
  { label: "Dashboard" },
  { label: "Users", onClick: () => console.log("navigated") },
]);

// Set actions menu
AssemblyBridge.header.setActionsMenu([
  { label: "Download", icon: "Download", onClick: () => downloadFile() },
  {
    label: "Delete",
    icon: "Trash",
    color: "red",
    onClick: () => confirmDelete(),
  },
]);
```

## API 参考

### `AssemblyBridge.header`

#### `setBreadcrumbs(items)`

在信头中设置面包屑导航项 .

```typescript
AssemblyBridge.header.setBreadcrumbs([
  { label: "Home" },
  { label: "Projects", onClick: () => navigateToProjects() },
  { label: "Current Project" },
]);
```

**参数:**

-   `items`: 阵列 `{ label: string, onClick?: () => void }`

#### `setPrimaryCta(config)`

设置或清除主 CTA 按钮 .

```typescript
// Set a CTA
AssemblyBridge.header.setPrimaryCta({
  label: "Save Changes",
  icon: "Check",
  onClick: () => save(),
});

// Clear the CTA
AssemblyBridge.header.setPrimaryCta(null);
```

**参数:**

-   `config`数字 : `{ label: string, icon?: Icon, onClick: () => void }` 或者说 `null`

#### `setSecondaryCta(config)`

设置或清除二级 CTA 按钮 。 与 API 相同 `setPrimaryCta`。 。 。 .

#### `setActionsMenu(items)`

设定动作下放菜单项 .

```typescript
AssemblyBridge.header.setActionsMenu([
  { label: "Archive", icon: "Archive", onClick: () => archive() },
  { label: "Delete", icon: "Trash", color: "red", onClick: () => remove() },
]);
```

**参数:**

-   `items`: 阵列 `{ label: string, icon?: Icon, color?: 'red', onClick: () => void }`

### `AssemblyBridge.configure(config)`

配置附加设置的桥.

```typescript
AssemblyBridge.configure({
  additionalOrigins: ["portal.yourcompany.com", "https://custom-domain.com"],
  debug: true, // Enable debug logging
});
```

**参数:**

-   `config.additionalOrigins`: 由起源排列,允许Message后通信. HTTPS 不设协议的出处。 可以称为多倍-由来是累积的.
-   `config.debug`: 当信件无法发送时, 启用调试模式将警告日志到控制台( 例如, 父来源不在允许列表中, 不在 iframe 中运行) 。 对解决问题有用.

**说明:** 该桥包括内部支持 `*.copilot.app`, (中文(简体) ), `*.myassembly.com`, (中文(简体) ), `dashboard.assembly.com`当地人, 和他们的等效。 你只需要用这个 `configure()` 用于自定义门户域。 父源是从第一个经源码验证的父源消息中得知的—— `document.referrer` 未使用.

### `AssemblyBridge.navigate(route, options?)`

在父应用程序中导航不同的路由 .

```typescript
// Navigate to settings
AssemblyBridge.navigate("settings");

// Navigate to a specific app
AssemblyBridge.navigate("apps", { id: "app-123" });

// Navigate to a specific form
AssemblyBridge.navigate("forms", { id: "form-456" });
```

**参数:**

-   `route`: 所支持的路线之一(见下文)
-   `options`: 可选 `{ id?: string }`

### `AssemblyBridge.navigateTo(destination, options?)`

导航到打入的目的地并等待主机的确认. 返回一个与 `{ ok: true }` 关于成功, `{ ok: false, reason }` 当主机拒绝导航时,或在超时后拒绝,如果主机从未响应.

TypeScript在编译时间强制每个目的地所需的参数.

```typescript
// Navigate to a specific invoice
const result = await AssemblyBridge.navigateTo({ to: "invoice", invoiceId: "inv_abc" });
if (!result.ok) {
  console.warn("Navigation rejected:", result.reason);
}

// Navigate to a client detail page
await AssemblyBridge.navigateTo({ to: "client", clientId: "cli_xyz", tab: "notes" });

// Navigate to home
await AssemblyBridge.navigateTo({ to: "home" });
```

**支持的目的地:**

| `to` | 所需参数 | 可选段落 |
| --- | --- | --- |
| `home` | —— 说 | —— 说 |
| `client` | `clientId` | `tab` |
| `company` | `companyId` | `tab` |
| `channel` | —— 说 | `channelId` |
| `files` | —— 说 | `channelId` |
| `contract` | `contractId` | —— 说 |
| `form` | `formId` | —— 说 |
| `formResponse` | `formId`, (中文(简体) ), `responseId` | —— 说 |
| `invoice` | `invoiceId` | —— 说 |
| `subscription` | `subscriptionId` | —— 说 |
| `product` | —— 说 | —— 说 |
| `helpdesk` | —— 说 | —— 说 |
| `article` | `articleId` | —— 说 |
| `notifications` | —— 说 | —— 说 |
| `automations` | —— 说 | —— 说 |
| `settings` | —— 说 | `page` |
| `app` | `installId` | —— 说 |

**选项 :**

-   `replace`: 替换当前历史条目而不要按 (默认 : `false`(中文(简体) )
-   `newTab`: 在新标签中打开( 默认 ): `false`(中文(简体) )
-   `timeout`: Miliseconds 等待主机确认后再拒绝(默认 : `10000`(中文(简体) )

### `AssemblyBridge.location.report(path, search, replace?)`

向主机报告应用程序当前位置 。 每一次客户端路由更改都叫这个 这个 `path` 必须剥去表面前缀——报告 `/orders/42`没有 `/c/orders/42`。 。 。 .

```typescript
AssemblyBridge.location.report("/orders/42", "?tab=details");
AssemblyBridge.location.report("/dashboard", "");
// Signal a replace (no new history entry on the host):
AssemblyBridge.location.report("/settings", "", true);
```

**参数:**

-   `path`: App-local path,表面前缀剥离(例如. `/orders/42`) (中文(简体) ).
-   `search`: 查询字符串,包括主线 `?`,或 `''` 当缺席时.
-   `replace`: 当 `true`,东道主应该取代其历史条目而不是推.

### `AssemblyBridge.location.onNavigate(handler)`

当主机发送一个 `location.navigate` 命令。 处理者收到 `{ path, search, replace? }` 没有表面前缀的有效载荷——应用在通航前必须重新添加自己的前缀.

```typescript
AssemblyBridge.location.onNavigate(({ path, search, replace }) => {
  const destination = `/c${path}${search}`;
  if (replace) {
    router.replace(destination);
  } else {
    router.push(destination);
  }
});
```

**参数:**

-   `handler`: 调用 `{ path: string; search: string; replace?: boolean }`。 。 。 .

### 支持的数值

#### 图标

CTA 可用: `Archive`, (中文(简体) ), `Plus`, (中文(简体) ), `Templates`, (中文(简体) ), `Trash`, (中文(简体) ), `Check`

可用于动作菜单项 : `Archive`, (中文(简体) ), `Plus`, (中文(简体) ), `Templates`, (中文(简体) ), `Trash`, (中文(简体) ), `Download`, (中文(简体) ), `Check`, (中文(简体) ), `Disconnect`

#### 路线

-   `apps` - 应用程序页面(支持) `id` 用于特定应用程序)
-   `billing` - 账单页
-   `contracts` - 合同页
-   `files` - 文件页面(支持) `id` 用于频道)
-   `forms` - 窗体页面(支持) `id` 具体形式)
-   `helpdesk` - 服务台网页(支助) `id` 关于具体条款)
-   `invoices` - 发票页
-   `messages` - 信件页面(支持) `id` 用于频道)
-   `notifications` - 通知页(支持) `id` 用于频道)
-   `settings` - 设置页面
-   `settings.billing` - 计费设置
-   `settings.profile` - 配置设置
-   `products.create` - 创建产品页面
-   `products.edit` - 编辑产品页面(支持) `id` (用于产品)

## 类型脚本支持

该套件包括了TypeScript声明. 视需要导入类型:

```typescript
import type {
  BreadcrumbItem,
  CtaConfig,
  ActionMenuItem,
  Route,
  Icon,
  NavigateDestination,
  NavigateToOptions,
  NavigateResult,
} from "@assembly-js/app-bridge";
```

## 发展

```bash
# Install dependencies
yarn install

# Build
yarn build

# Type check
yarn type-check

# Run tests
yarn test

# Generate content-hashed files
yarn generate-manifest
```

## 许可证

麻省理工学院

## 常见问题

### @assembly-js/app-bridge 是什么？

用于自定义应用程序和Copilot母应用程序之间Message后通信的帮助器功能

### 如何安装 @assembly-js/app-bridge？

在项目目录运行 npm install @assembly-js/app-bridge，或使用 pnpm add / yarn add / bun add。

### @assembly-js/app-bridge 支持 TypeScript 吗？

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

### @assembly-js/app-bridge 支持 ESM 还是 CommonJS？

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

### @assembly-js/app-bridge 可以商用吗？

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

### @assembly-js/app-bridge 的下载量有多少？

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

### @assembly-js/app-bridge 还在维护吗？

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