# @fluid-app/widget-runtime 中文文档

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

版本：0\.1\.271
npm 元数据更新时间：2026-11-15T15:07:36.629Z
中文译文更新时间：2026-11-15T01:40:35.948Z
软件包许可：未声明

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

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

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

- 包体积（解压后）：1 MB，50 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：6 个
- peer 依赖：react \>=18\.0\.0，react-dom \>=18\.0\.0
- 首次发布：2026-07-22T21:43:57.276Z
- 最新版本发布：2026-11-15T15:07:36.464Z
- 近 30 天下载量：29063（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：272（近 12 个月 272 个）

## 中文简介

Fluid 部件包的远程 DOM 主机和工人运行时间

## 安装

```sh
npm install @fluid-app/widget-runtime
```

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

## README

# `@fluid-app/widget-runtime`

第三方流体部件的远程 DOM 运行时间 .

该套装有两个故意的小型公共出入口:

-   `@fluid-app/widget-runtime` 将部件工人挂入主机元素.
-   `@fluid-app/widget-runtime/worker` 启动一个包含作者的 React 部件并曝光已声明的主机能力的工人.

元件发现,描述验证,目录访问,出版,和建设者注册属于"门户"包和"CLI". 此软件包只拥有主机/ 工人执行边界 .

## 东道主

门户网站应用应当使用门户网站SDK主机. 它拥有整个 已审查 Fluid UI 渲染器映射并保存部件内的组件覆盖 阴入根. 该应用程序只提供编译的阴影根 CSS :

```tsx
import { createPortal } from "@fluid-app/portal-sdk";
import fluidComponentCssUrl from "@fluid-app/portal-sdk/remote-widget-shadow.css?url";

createPortal({
  remoteWidgets: { fluidComponentCssUrls: [fluidComponentCssUrl] },
});
```

当前的门户网站应用程序和生成的门户网站启动器包含此内容 配置 。 Mist的直接活预览主机 提供同样的渲染器地图, 封装包装, 样式表作为内置 CSS .

`mountRemoteDomWidget()` 是低级主机API. 直接消费者 当前流体部件工人必须提供所有三个流体 UI 主机部件 :

-   已审查 `componentRenderers` 地图;
-   (单位:千美元) `wrapRemoteRoot` 包含部件领域门户的执行;
-   匹配 `fluidComponentCssText` 或者说 `fluidComponentCssUrls`。 。 。 .

运行时间只广告 Fluid UI 合同 v2 当每个 v2 渲染器是 现相. 因此,流体UI工人未能进行合同谈判,而不是 以一个带部分渲染器的宿主标出.

```tsx
import { mountRemoteDomWidget } from "@fluid-app/widget-runtime/remote-dom";
import {
  REMOTE_DOM_COMPONENT_RENDERERS,
  wrapRemoteDomRoot,
} from "@fluid-app/portal-sdk";
import fluidComponentCssUrl from "@fluid-app/portal-sdk/remote-widget-shadow.css?url";

const handle = mountRemoteDomWidget({
  host: document.querySelector("#widget")!,
  artifact: {
    packageId: "example.widgets",
    version: "1.0.0",
    widgetType: "Greeting",
    workerEntryUrl: "https://cdn.example.com/widget.js",
    cssUrls: [],
    assetUrls: [],
    capabilities: [{ name: "account", version: "1" }],
  },
  props: { name: "Ada" },
  componentRenderers: REMOTE_DOM_COMPONENT_RENDERERS,
  wrapRemoteRoot: wrapRemoteDomRoot,
  fluidComponentCssUrls: [fluidComponentCssUrl],
  callCapability: (capability, method, payload) =>
    portalCapabilities.call(capability, method, payload),
});

await handle.ready;
handle.updateProps({ name: "Grace" });
handle.dispose();
```

每个挂载创建一个模块工人和一个远程DOM线程. 处置释放出线程,工人,风格,事件听众,并变成节点. 主机在将所有突变,URL,CSS,事件,和可序列的值应用到阴影根之前,先进行消毒.

## 工人

```tsx
import {
  startRemoteDomWidgetWorker,
  useRemoteDomCapability,
} from "@fluid-app/widget-runtime/worker";

function Greeting({ name }: { readonly name: string }) {
  const account = useRemoteDomCapability("account");
  return (
    <button onClick={() => account.call("openProfile")}>Hello {name}</button>
  );
}

startRemoteDomWidgetWorker({ widgets: { Greeting } });
```

工人可以通过上游远程DOM来提供任意支持的HTML和CSS. 运行时间会禁用存储,筑巢工人,新现实,以及工人环境允许的非牵线网全球. 主机呼叫仅限于部件包描述符所声明的能力.

`fetch` 被拒绝, 除非选定部件声明 `networkAccess` 版本 `1` 和东道主供应 确切持续赠款。 允许的电话直接打 通过保存的本地工人获取; 运行时间不注入流体 证书或信头。 初始 URL 无法地址 `fluid.app`,东道主 出入口来源,回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回回 DNS 分辨率和重定向 不检查目的地。 因此,重新定向可以达到以下目标: 将会被拒绝作为初始 URL 。 WebSocket, 事件來源, V1中仍然没有Web Transport和流式特定API.

## 威胁模式

部件目录批准是信任决定: 核准的软件包是信任的 由公司或Droplet所有者提供的应用程序代码。 全球工人组织 锁定、能力验证、突变消毒、URL政策、资源 限制, 阴影根隔离 是在信任的周围进行深入的防御 代码。 它们保护宿主DOM和狭窄的意外环境访问,但是它们 不构成完整的网络沙盒或替代软件包 审查、目录授权、浏览器隔离或服务器侧访问 控制系统.

网络化代码可以将该部件可用的任何门户数据发送到一个 对外服务。 工人隔离不能保护Fluid的名誉 软件包行为的域; 目录、 构建器和 CLI 批准必须处理 作为出版商信任决定的网络访问.

## 非目标

-   没有经典脚本加载或浏览器全局 .
-   没有遗留部件注册或描述符转换 .
-   没有目录或软件包验证 API.
-   没有工人聚集,心跳,诊断框架, 或版本失效.
-   遗产门户SDK钩子没有兼容层.

## 常见问题

### @fluid-app/widget-runtime 是什么？

Fluid 部件包的远程 DOM 主机和工人运行时间

### 如何安装 @fluid-app/widget-runtime？

在项目目录运行 npm install @fluid-app/widget-runtime，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=18\.0\.0）、react-dom（\>=18\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @fluid-app/widget-runtime 支持 TypeScript 吗？

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

### @fluid-app/widget-runtime 支持 ESM 还是 CommonJS？

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

### @fluid-app/widget-runtime 可以商用吗？

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

### @fluid-app/widget-runtime 的下载量有多少？

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

### @fluid-app/widget-runtime 还在维护吗？

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