# @getflip/bridge 中文文档

规范地址：https://npmcn.com/package/%40getflip/bridge/

版本：0\.11\.91
npm 元数据更新时间：2026-11-10T13:32:55.216Z
中文译文更新时间：2026-11-16T06:04:30.039Z
软件包许可：SEE LICENSE IN LICENSE\.md

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

原始 npm 页面：https://www.npmjs.com/package/%40getflip/bridge
原文对照：https://npmcn.com/package/%40getflip/bridge/?lang=original
项目主页：https://github.com/getflip/swirl#readme
源码仓库：https://github.com/getflip/swirl

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

- 包体积（解压后）：126 kB，133 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2022-12-01T07:48:43.604Z
- 最新版本发布：2026-11-10T13:32:54.807Z
- 近 30 天下载量：10233（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：949（近 12 个月 275 个）

## 中文简介

翻转JavaScript Bridge用于外部集成.

## 安装

```sh
npm install @getflip/bridge
```

也可以使用：`pnpm add @getflip/bridge`、`yarn add @getflip/bridge`、`bun add @getflip/bridge`

## README

# 翻转桥

翻转桥处理您嵌入的应用程序和翻转之间的通信 App或翻转控制台.

**目录**

-   [安装](https://npmcn.com/package/%40getflip/bridge/#readme-installation)
-   [使用量](https://npmcn.com/package/%40getflip/bridge/#readme-usage)
-   [方法](https://npmcn.com/package/%40getflip/bridge/#readme-methods)
    -   [国际化](https://npmcn.com/package/%40getflip/bridge/#readme-internationalization)
    -   [导航](https://npmcn.com/package/%40getflip/bridge/#readme-navigation)
    -   [他们](https://npmcn.com/package/%40getflip/bridge/#readme-theming)
    -   [对话框](https://npmcn.com/package/%40getflip/bridge/#readme-dialogs)
    -   [模块](https://npmcn.com/package/%40getflip/bridge/#readme-modals)
    -   [土司](https://npmcn.com/package/%40getflip/bridge/#readme-toasts)
    -   [下载](https://npmcn.com/package/%40getflip/bridge/#readme-download)
-   [活动](https://npmcn.com/package/%40getflip/bridge/#readme-events)
-   [处理错误](https://npmcn.com/package/%40getflip/bridge/#readme-error-handling)
-   [发展](https://npmcn.com/package/%40getflip/bridge/#readme-development)

## 安装

```sh
npm install --save @getflip/bridge
# or
yarn add @getflip/bridge
```

## 使用量

库会显示一组功能和听众,您可以用来进行交流 与 Flip App 和 Flip Admin Console (host App for short) 相通.

**在使用所提供的函数之前,您必须先拨打 `initFlipBridge` 函数来设置翻转桥.**

```js
import { initFlipBridge } from "@getflip/bridge";

initFlipBridge({
  debug: true,
  hostAppOrigin: "http://localhost:4200", // has to be the origin of the targeted host app
});
```

## 方法

### 国际化

#### `getAvailableLangs`

获取主机应用程序的所有可用语言.

**回返** `Promise<string[]>`

**示例**

```js
import { getAvailableLangs } from "@getflip/bridge";

const availableLanguages = await getAvailableLangs(); // e.g. ['de', 'en', 'fr', …]
```

#### `getLang`

获取主机应用程序的当前语言.

**回返** `Promise<string>`

**示例**

```js
import { getLang } from "@getflip/bridge";

const currentLanguage = await getLang(); // e.g. 'en'
```

### 导航

#### `navigate`

导航到特定路线.

**参数** `string`

**回返** `Promise<boolean>`

**示例**

```js
import { navigate } from "@getflip/bridge";

await navigate("/my-app/settings");
```

#### `close`

请主机应用程序关闭当前集成( 例如, 和 主办方的背部或密切控制。 当您提供自己的信头和 要返回自定义或关闭按钮, 而不是依赖主机 .

**回返** `Promise<boolean>`

**示例**

```js
import { close } from "@getflip/bridge";

await close();
```

### 他们

#### `getTheme`

获取当前主题 .

**回返**

```js
Promise<{
  activeTheme: "light" | "dark";
  preferredTheme: "light" | "dark" | undefined;
}>
```

**示例**

```js
import { getTheme } from "@getflip/bridge";

const theme = await getTheme();
```

#### `setTheme`

设定主题. 过 `undefined` 用于重置用户的系统主题.

**参数** `"light" | "dark" | undefined`

**回返** `Promise<"light" | "dark" | undefined>`

**示例**

```js
import { setTheme } from "@getflip/bridge";

const newTheme = await setTheme("dark");
```

### 对话框

#### `createDialog`

创建由主机应用程序提供的模式对话框 .

**参数**

```js
{
  hideLabel?: boolean;
  id: string;
  intent?: 'primary' | 'critical';
  label: string;
  text: string;
  primaryAction?: {
    label: string;
  };
  secondaryAction?: {
    label: string;
  };
}
```

**回返**

```js
Promise<boolean>
```

**示例**

```js
import { createDialog } from "@getflip/bridge";

const dialog = await createDialog({
  id: "my-dialog",
  label: "My Dialog",
  text: "Lorem ipsum",
  primaryAction: {
    label: "Close",
  },
});
```

#### `openDialog`

打开对话框.

**参数**

```js
{
  id: string; // the dialog id
}
```

**回返** `Promise<boolean>`

**示例**

```js
import { createDialog, openDialog } from "@getflip/bridge";

await createDialog({
  id: "my-dialog",
  label: "My Dialog",
  text: "Lorem ipsum",
});

await openDialog({ id: "my-dialog" });
```

#### `closeDialog`

关闭对话框 .

**参数**

```js
{
  id: string; // the dialog id
}
```

**回返** `Promise<boolean>`

**示例**

```js
import { closeDialog } from "@getflip/bridge";

await closeDialog({ id: "my-dialog" });
```

#### `destroyDialog`

破坏对话框, 从 DOM 中删除 .

**参数**

```js
{
  id: string; // the dialog id
}
```

**回返** `Promise<boolean>`

**示例**

```js
import { destroyDialog } from "@getflip/bridge";

await destroyDialog({ id: "my-dialog" });
```

### 模块

#### `createModal`

创建由主机应用程序提供的模式 。 模式将显示通过的 URL 为 一个iFrame.

**参数**

```js
{
  id: string;
  label: string;
  primaryAction?: {
    label: string;
  };
  secondaryAction?: {
    label: string;
  };
  url: string;
}
```

**回返**

```js
Promise<boolean>
```

**示例**

```js
import { createModal } from "@getflip/bridge";

const modal = await createModal({
  id: "my-moadl",
  label: "My Modal",
  primaryAction: {
    label: "Close",
  },
  url: "https://google.com",
});
```

#### `openModal`

打开一个模式.

**参数**

```js
{
  id: string; // the modal id
}
```

**回返** `Promise<boolean>`

**示例**

```js
import { createModal, openModal } from "@getflip/bridge";

await createModal({
  id: "my-modal",
  label: "My Modal",
  url: "https://google.com",
});

await openModal({ id: "my-modal" });
```

#### `closeModal`

关闭一个模式.

**参数**

```js
{
  id: string; // the modal id
}
```

**回返** `Promise<boolean>`

**示例**

```js
import { closeModal } from "@getflip/bridge";

await closeModal({ id: "my-modal" });
```

#### `destroyModal`

摧毁一个模式,把它从DOM中移除.

**参数**

```js
{
  id: string; // the modal id
}
```

**回返** `Promise<boolean>`

**示例**

```js
import { destroyModal } from "@getflip/bridge";

await destroyModal({ id: "my-modal" });
```

### 土司

#### `showToast`

由主机应用显示敬酒.

**参数**

```js
{
  text: string;
  duration?: number;
  icon?: string;
  intent?: SwirlToastIntent;
}
```

**回返** `Promise<boolean>`

**示例**

```js
import { showToast } from "@getflip/bridge";

await showToast({
  text: "My toast",
  duration: 5000,
  icon: "icon",
  intent: "success",
});
```

### 下载

#### `download`

通过主机应用程序下载文件 .

**参数**

```js
{
  fileName: string; // filename
  fileType: string; // file type
  url?: string; // optional file URL
  dataUrl?: string; // optional base64 encoded file data
}
```

**回返** `Promise<boolean>`

**示例**

```js
import { download } from "@getflip/bridge";

await download({
  fileName: "my-file.txt",
  fileType: "text/plain",
  url: "https://example.com/my-file.txt",
});
```

## 活动

使用 `subscribe` 函数以订阅事件.

```js
import { subscribe, BridgeEventType } from "@getflip/bridge";

const unsubscribe = await subscribe(BridgeEventType.THEME_CHANGE, (event) => {
  console.log(event.data);
});

// …

await unsubscribe();
```

### `NAVIGATION_END`

当应用程序成功导航到不同的路线时会起火.

**活动**

```js
{
  data: {
    route: string; // e.g. '/notifications'
  }
  type: BridgeEventType.NAVIGATION_END;
}
```

### `LANG_CHANGE`

当用户选择语言更改时会开火 .

**活动**

```js
{
  data: string; // e.g. 'en'
  type: BridgeEventType.LANG_CHANGE;
}
```

### `PRIMARY_ACTION_CLICK`

当单击对话框或模式的主动作按钮时起火 .

**活动**

```js
{
  data: {
    parentId: string; // id of the action's dialog or modal
  }
  type: BridgeEventType.PRIMARY_ACTION_CLICK;
}
```

### `SECONDARY_ACTION_CLICK`

当单击对话框或模式的次要动作按钮时点火 .

**活动**

```js
{
  data: {
    parentId: string; // id of the action's dialog or modal
  }
  type: BridgeEventType.SECONDARY_ACTION_CLICK;
}
```

### `THEME_CHANGE`

用户主题改变时起火.

**活动**

```js
{
  data: {
    activeTheme: "light" | "dark";
    preferredTheme: "light" | "dark" | undefined;
  }
  type: BridgeEventType.THEME_CHANGE;
}
```

### `TITLE_CHANGE`

当应用程序的 HTML 标题标签值改变时, 点火 .

**活动**

```js
{
  data: {
    title: string;
  }
  type: BridgeEventType.TITLE_CHANGE;
}
```

## 处理错误

所有已提供的函数返回执行时出现错误的保证 失败 。 错误的格式如下.

```js
{
  code: BridgeErrorCode; // e.g. 'FORBIDDEN_ORIGIN'
}
```

### `FORBIDDEN_ORIGIN`

当主机应用不允许请求的应用程序的出处时被抛出. 请检查您的应用程序是否在 Flip 合伙人 Dashboard 中正确注册 编辑 `hostAppOrigin` 选项已设定(参见 [使用量](https://npmcn.com/package/%40getflip/bridge/#readme-usage)) (中文(简体) ).

### `INVALID_REQUEST`

主机应用确定请求无效 。 这通常发生在 参数无效.

## 发展

以监视模式启动编译器用于本地开发 :

```
yarn dev
```

生产建设和释放是通过我们的Github工作流程进行管理的。 确保 创建更改集 `yarn changeset` 如果你想触发一个新的 释放.

## 常见问题

### @getflip/bridge 是什么？

翻转JavaScript Bridge用于外部集成\.

### 如何安装 @getflip/bridge？

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

### @getflip/bridge 支持 TypeScript 吗？

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

### @getflip/bridge 支持 ESM 还是 CommonJS？

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

### @getflip/bridge 可以商用吗？

@getflip/bridge 使用 SEE LICENSE IN LICENSE\.md 许可。许可条款写在包内的独立文件中，请阅读该文件确认可否商用。以上为概括，不构成法律意见，请以许可原文为准。

### @getflip/bridge 的下载量有多少？

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

### @getflip/bridge 还在维护吗？

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

