@getflip/bridge

中文文档
0.11.91发布于 2026/11/10SEE LICENSE IN LICENSE.mdTypeScriptESM + CJS构建来源已验证近 30 天下载 1万

翻转JavaScript Bridge用于外部集成.

中文使用文档
文档目录21 节
  1. 安装
  2. 使用量
  3. 方法
  4. 国际化
  5. 导航
  6. 他们
  7. 对话框
  8. 模块
  9. 土司
  10. 下载
  11. 活动
  12. NAVIGATION_END
  13. LANG_CHANGE
  14. PRIMARY_ACTION_CLICK
  15. SECONDARY_ACTION_CLICK
  16. THEME_CHANGE
  17. TITLE_CHANGE
  18. 处理错误
  19. FORBIDDEN_ORIGIN
  20. INVALID_REQUEST
  21. 发展

翻转桥

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

目录

安装

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

使用量

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

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

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[]>

示例

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

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

getLang

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

回返 Promise<string>

示例

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

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

导航

navigate

导航到特定路线.

参数 string

回返 Promise<boolean>

示例

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

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

close

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

回返 Promise<boolean>

示例

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

await close();

他们

getTheme

获取当前主题 .

回返

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

示例

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

const theme = await getTheme();

setTheme

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

参数 "light" | "dark" | undefined

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

示例

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

const newTheme = await setTheme("dark");

对话框

createDialog

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

参数

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

回返

Promise<boolean>

示例

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

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

openDialog

打开对话框.

参数

{
  id: string; // the dialog id
}

回返 Promise<boolean>

示例

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

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

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

closeDialog

关闭对话框 .

参数

{
  id: string; // the dialog id
}

回返 Promise<boolean>

示例

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

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

destroyDialog

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

参数

{
  id: string; // the dialog id
}

回返 Promise<boolean>

示例

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

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

模块

createModal

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

参数

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

回返

Promise<boolean>

示例

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

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

openModal

打开一个模式.

参数

{
  id: string; // the modal id
}

回返 Promise<boolean>

示例

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

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

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

closeModal

关闭一个模式.

参数

{
  id: string; // the modal id
}

回返 Promise<boolean>

示例

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

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

destroyModal

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

参数

{
  id: string; // the modal id
}

回返 Promise<boolean>

示例

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

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

土司

showToast

由主机应用显示敬酒.

参数

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

回返 Promise<boolean>

示例

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

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

下载

download

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

参数

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

回返 Promise<boolean>

示例

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

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

活动

使用 subscribe 函数以订阅事件.

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

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

// …

await unsubscribe();

NAVIGATION_END

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

活动

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

LANG_CHANGE

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

活动

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

PRIMARY_ACTION_CLICK

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

活动

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

SECONDARY_ACTION_CLICK

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

活动

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

THEME_CHANGE

用户主题改变时起火.

活动

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

TITLE_CHANGE

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

活动

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

处理错误

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

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

FORBIDDEN_ORIGIN

当主机应用不允许请求的应用程序的出处时被抛出. 请检查您的应用程序是否在 Flip 合伙人 Dashboard 中正确注册 编辑 hostAppOrigin 选项已设定(参见 使用量) (中文(简体) ).

INVALID_REQUEST

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

发展

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

yarn dev

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

版本与发布记录

@getflip/bridge 共发布 949 个版本,首次发布于 2022/12/01;过去 12 个月发布了 275 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
0.11.91latest2026/11/105 天前
0.11.902026/11/0610 天前
0.11.892026/11/0510 天前
0.11.89-beta-20261105095642beta2026/11/0510 天前
0.11.882026/11/0412 天前
0.11.872026/10/2323 天前

其他发布通道:new-shell → 0.0.0-new-shell-20231130132058,beta → 0.11.89-beta-20261105095642。

关于 @getflip/bridge 的常见问题

@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 和提交记录判断。