# @fluid-app/droplet-bridge 中文文档

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

版本：0\.1\.112
npm 元数据更新时间：2026-11-11T23:39:10.382Z
中文译文更新时间：2026-11-15T02:03:03.014Z
软件包许可：未声明

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

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

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

- 包体积（解压后）：344 kB，10 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2026-10-12T04:54:08.178Z
- 最新版本发布：2026-11-11T23:39:10.216Z
- 近 30 天下载量：19230（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：114（近 12 个月 114 个）

## 中文简介

Fluid嵌入式app会话符号和上下文的浏览器 SDK .

## 安装

```sh
npm install @fluid-app/droplet-bridge
```

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

## README

# @ fluid-app/ 滴滴桥

嵌入式液滴的 Canonical 浏览器客户端 .

开发者指南 : [文件/滴滴-桥-开发指南.md](https://npmcn.com/docs/droplet-bridge-developer-guide.md)。 。 。 .

```ts
import { createFluidBridge } from "@fluid-app/droplet-bridge";

const bridge = createFluidBridge({ clientId, hostOrigin });
const context = await bridge.getContext();
const token = await bridge.getSessionToken();
await fetch("/api/embedded-action", { method: "POST" });
// Use disableFetchPatch: true to opt out of ambient fetch.
await bridge.fetch("/api/embedded-action", { method: "POST" });
// Component teardown, or explicit shutdown:
bridge.destroy();
```

`hostOrigin` 是由外壳提供的 HTTP( S) 主机壳源 。 客户 仅接受来源,并 `window.parent`它在发送前安装其听众 UUID-v7 (英语) `bridge.ready`,最多重复8次,并设定后退直到上下文 并拒绝10秒后不完全的握手 议定书或 SDK 不匹配因打出错误而失效 。 只有一位客户拥有文件 时间; 在创建另一个之前销毁它。 真正的导航 `pagehide` (单位:千美元)`persisted: false`和 `unload` 自动销毁。 A 类 `pagehide` 输入 后/前缓存( n)`persisted: true`) 使桥梁完好无损——文件是 冻了,没走.. `pageshow` 恢复未解决的握手问题 已经解决了的人 工作不变.

`getContext()` 1. 解决在握手时交付的不可改变、未签字的铁路背景; 它从不按要求获取上下文. `getSessionToken()` 请求仅更新身份 符号 `session_token.refresh_request` 每一次,同时召集呼叫者 在飞行请求。 SDK会从信使那里刷新 寿命相对于收款,绝不从比较 `exp` 对这个客户的时钟.. 管理员的本地时钟可以比主机运行得早 短命的标志必须 不被拒绝,或每分每秒地被更新, 解码是用来送货的 并仅排程: 滴入后端验证签名、身份和过期 页:1 [核查合同](https://npmcn.com/apps/rails/docs/droplet-session-token-verification-contract.md)。 。 。 . SDK使用对应用/商店/演员/演员/进场/住宿装订并忽略的内装交付 对未知或先前文件要求的ID作出答复.

明确和环境获取仅在服务器交付的精确源头进行认证 `fetch.allowedOrigins`。没有框架 `appOrigins` 选项。 流体 API 源代码为 即使意外列出,也先排除。 环境采集也通过请求 只要握起手来 失败, 或仍在等待处理, 请求针对的是当前以外的来源 文档是自己的。 明确驳回的请求;环境驳回的请求通过 包括提及环境 之前抓获的包装器 `destroy()`每一次通过它发出的不同来源的呼叫 ;通过同一参考的同源呼叫一直失败. 允许请求保存请求机构, 页眉和证书,用新的会话符号替换授权,并发送 查看器活动语言为 `Accept-Language` 从 `store.locale`。缺少区域 未关闭 。 相对请求 URL 解决当前文档位置, 在呼叫时读取,所以文档中的路由更改被尊重. 明确桥接取 拒绝方向调整 `redirect: "error"` ——浏览器将授权页眉剥去 跨源重定向,所以转发后将无保障,而且 将 HTTP 401/403 转换为打出错误。 Ambient 抓取保持呼叫者自己的方向 模式和返回 401/403 作为普通响应,因为同源应用程序代码预计 读取自己的反应状态。 网络失败返回未回复的输入错误 两个路径上的正文或原始例外文本. `destroy()` 恢复上一个获取, 取消计时器并拒绝拖放请求.

## 第一次请求和以后的文件

URL 网络 `session_token` 实值 **只有第一请求服务器拖曳**SDK把它剥了 立即与 `history.replaceState` 并且从不使用它作为浏览器证书. 滴答必须设置 `Referrer-Policy: no-referrer` 在子资源加载之前; iframe的裁判政策并不保护这些次资源。 不完全日志 本地Storage、会话Storage、 cookie 或 粘接桥符 窗口。名称.

Iframe 内部的全文件导航会保留该滴流的当前路径 。 内容 服务器必须将任何 URL 令牌当作靴后缺失, 使用自己的短 Http 应用会话由已核实的第一负载身份建立,或使桥接第一 恢复页面。 恢复页将这个SDK初始化,并发送出一个新的桥牌 用于核查。 已失效的 URL 符号不能硬失败恢复 . 每个新文档再次初始化 SDK 并获得新的上下文/ 托盘 后弥. 东道主必须 **不重写被冻结的 iframe sc** 以注入另一个 因为它会重设货车的路线。 一个应用会话饼干 存储应用程序的自定义会话, 而不是流线桥符号 .

## 冠状主机

`createCanonicalBridgeHost` 使用共享版本协议。 认证外壳 提供注册的应用程序来源和固定挂载:客户端、商店、演员、安装、, 输入和编号。 在第一个 URL 薄荷 之前创建 sid 并将其再用于同一挂载 . 储存/演员/安装/入口/资源变化摧毁主机和iframe并创建 新挂载; 在同一挂载内文档导航保存 src 和 sid .

每个有效 `bridge.ready` 获取当前授权的服务器上下文和新内容 薄荷,包括在第一个文件之后. 同样的飞行准备状态ID的重试 组合;即使老工作尚未完成,新文档标识也会进行。 准备情况 刷新每一个都有自己的 界限待定的游泳池, 所以暴风雨刷新永远不会 新文档的成本 `bridge.ready` (单位:千美元) `host_unavailable`。客户端忽略旧的 关联性、与交付的 sid 连接、并联 `getSessionToken()` 呼叫机内更新请求 两个主机 适配器必须尊重中止信号并执行未标记的授权请求。 刷新 重新检查上下文和 SDK 相容性后再计时 。 刷新也拒绝薄荷, 将文档中已有的上下文和符号保留在原名 从此之后,从授权的现场上下文中删除了在座的货品 将驱离与任何来源的结合进行比较 `bridge.ready` 在此挂载时, 绝对不要与一个值相对立 因此,先前的删除不能隐藏在后来的添加之后。 这个基线 是整个挂载的单调,而不是由后置重置 `bridge.ready`: 主机 无法可靠地从重复或重审的文档中看出新文档的准备状态 来自同一文档( SDK 重试种族, 或 bfcache) `pageshow` 重新发送),所以 绝不允许复制已准备就绪者删除先前的去除。 原产地已删除 因此,中会不再为那座山的余生提供新的迹象, 即使对于删除后附加的文档; 重新装入管理页面到 重新挂载 Iframe 并取取新上下文 。 增加会中起源 平时很新鲜 适配器都不相信iframe身份或来源声明. `createFluidBridgeHost` 遗 物 门户网站在单独指定成员级别和 割地取来.

会话符号是身份断言,从不流出API证书. 后端 API 访问使用现有的 OAuth 客户端 证书流与存储资源并 安装范围许可执行。 导航和 shell UI 动作为 此客户端的符号/文本范围以外 .

## 常见问题

### @fluid-app/droplet-bridge 是什么？

Fluid嵌入式app会话符号和上下文的浏览器 SDK \.

### 如何安装 @fluid-app/droplet-bridge？

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

### @fluid-app/droplet-bridge 支持 TypeScript 吗？

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

### @fluid-app/droplet-bridge 支持 ESM 还是 CommonJS？

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

### @fluid-app/droplet-bridge 可以商用吗？

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

### @fluid-app/droplet-bridge 的下载量有多少？

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

### @fluid-app/droplet-bridge 还在维护吗？

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