# @fluid-app/portal-sdk 中文文档

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

版本：0\.1\.1433
npm 元数据更新时间：2026-11-15T14:50:21.270Z
中文译文更新时间：2026-11-15T01:32:51.426Z
软件包许可：未声明

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

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

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

- 包体积（解压后）：98.6 MB，1875 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：12 个
- peer 依赖：zod 4\.6\.5，react ^19\.2\.4，zustand ^5\.0\.9，react-dom ^19\.2\.4，lucide-react ~0\.575\.0，react-hook-form ^7\.64\.0，@hookform/resolvers ^5\.2\.2，@tanstack/react-query ^5\.90\.11
- 首次发布：2026-03-06T21:03:48.356Z
- 最新版本发布：2026-11-15T14:50:21.057Z
- 近 30 天下载量：147785（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：1423（近 12 个月 1423 个）

## 中文简介

用于自定义 Fluid 门户的 SDK

## 安装

```sh
npm install @fluid-app/portal-sdk
```

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

## README

# @fluid-app/portal-sdk (英语)

SDK用于构建自定义流出门户. 提供回放钩,提供商,以及一个API客户端与流体通商平台相融合.

## 安装

```bash
npm install @fluid-app/portal-sdk
# or
pnpm add @fluid-app/portal-sdk
# or
bun add @fluid-app/portal-sdk
```

### 同伴依赖关系

此软件包需要以下对等依赖性:

```json
{
  "react": ">=18.0.0",
  "@tanstack/react-query": ">=5.0.0"
}
```

## 快速启动

用 `FluidProvider`数字 :

```tsx
import { FluidProvider } from "@fluid-app/portal-sdk";

function App() {
  return (
    <FluidProvider
      config={{
        baseUrl: "https://api.fluid.app/api",
        getAuthToken: () => localStorage.getItem("fluid_token"),
        onAuthError: () => {
          // Handle 401 errors (e.g., redirect to login)
          window.location.href = "/login";
        },
      }}
    >
      <YourApp />
    </FluidProvider>
  );
}
```

## 远程部件架构

远程部件跨越了运行时的边界:部件代码在工人体内运行 门户SDK运行于浏览器主机. 执行工作按所有权划分:

-   `src/widgets/remote/contract/` 拥有共享的 JSON 安全协议 : 能力申报、门户功能元数据、可序列类型和 定制要素活动合同.
-   `src/widgets/remote/worker/` 拥有工人撰写和执行文件: `defineWidget`, (中文(简体) ), `defineWidgetPackage`, (中文(简体) ), `startWidgetPackage`和工人方面 元素包装器.
-   `src/widgets/remote/host/` 拥有门户集成:装入远程软件包, 能力处理者、登记册提供者、东道方要素登记 全屏协调.

依赖方向是 `worker → contract ← host`。工人代码绝不能 导入主机代码或仅依赖主机的用户, 如门户提供者、 DOM 渲染器或主机能力适配器.

### 公共场景

-   `@fluid-app/portal-sdk/widgets/worker` 是稳定的工人安全作者 外相为相. 部件包只应从此子路径导入工人 API .
-   `@fluid-app/portal-sdk` 是主机应用程序外观。 它暴露了门户 设置和配置主机所需的共享合同类型.
-   现有出口的东道公用事业,如 `@fluid-app/portal-sdk/utils/build-widget-registry`,保持兼容性 隐藏在主机执行上 以下路径 `src/widgets/remote/` 为: 内部而不是包入点.

### 词汇表

-   **合同** ——共享两个运行时间所理解的可序列的词汇 包含没有主机执行.
-   **工人** ——孤立的运行时间,使一个远程部件和呼叫 已宣布的门户功能.
-   **东道主** ——门户浏览器运行时间,可以给工人加载并落实他们的 已宣布的能力.
-   **能力** - 一个版本化的门户网站组函数组一个部件宣布和 主办方可以执行.
-   **外观** ——稳定包入,再出口内部实施 而不暴露其目录布局.

## 钩子

### 使用流体Profile

获取门户配置(主题、导航、屏幕) :

```tsx
import { useFluidProfile } from "@fluid-app/portal-sdk";

function Navigation() {
  const { data: profile, isLoading } = useFluidProfile();

  if (isLoading) return <Spinner />;

  return (
    <nav>
      {profile?.navigation.navigation_items.map((item) => (
        <NavItem key={item.id} item={item} />
      ))}
    </nav>
  );
}
```

### 使用Fluid主题

控制主题设置 :

```tsx
import { useFluidTheme } from "@fluid-app/portal-sdk";
import type { Theme } from "@fluid-app/portal-sdk";

function ThemeSwitcher({ themes }: { themes: Theme[] }) {
  const { currentTheme, setTheme, setThemeMode, mode } = useFluidTheme();

  return (
    <div>
      <select
        value={currentTheme?.name}
        onChange={(e) => {
          const theme = themes.find((t) => t.name === e.target.value);
          if (theme) setTheme(theme);
        }}
      >
        {themes.map((theme) => (
          <option key={theme.name} value={theme.name}>
            {theme.name}
          </option>
        ))}
      </select>

      <button onClick={() => setThemeMode(mode === "dark" ? "light" : "dark")}>
        Toggle {mode === "dark" ? "Light" : "Dark"} Mode
      </button>
    </div>
  );
}
```

## 供应商

### 流体提供器

建立SDK的主要提供者. 它包着:

-   `QueryClientProvider` (唐史答问
-   `FluidThemeProvider` (主题管理)

```tsx
import { FluidProvider } from "@fluid-app/portal-sdk";
import { QueryClient } from "@tanstack/react-query";

// Optional: provide your own QueryClient
const queryClient = new QueryClient({
  defaultOptions: {
    queries: { staleTime: 5 * 60 * 1000 },
  },
});

function App() {
  return (
    <FluidProvider
      config={{
        baseUrl: "https://api.fluid.app/api",
        getAuthToken: () => getToken(),
      }}
      queryClient={queryClient}
      initialTheme={defaultTheme}
    >
      <YourApp />
    </FluidProvider>
  );
}
```

### 流体主题

如果您不需要完整的 SDK 主题管理, 可以单独使用 :

```tsx
import { FluidThemeProvider, useFluidTheme } from "@fluid-app/portal-sdk";

function App() {
  return (
    <FluidThemeProvider initialTheme={myTheme}>
      <ThemedContent />
    </FluidThemeProvider>
  );
}
```

主题 CSS 变量应用到文档根( 或自定义的容器) 上 `--fluid-` 前缀.

## 类型

所有类型都导出用于您的应用程序 :

```tsx
import type {
  // Core types
  Profile,
  Navigation,
  NavigationItem,
  ScreenDefinition,

  // Client types
  FluidSDKConfig,
  RequestOptions,
} from "@fluid-app/portal-sdk";
```

## 查询密钥

查询密钥用于缓存无效和预选 :

```tsx
import { PROFILE_QUERY_KEY } from "@fluid-app/portal-sdk";
import { useQueryClient } from "@tanstack/react-query";

function RefreshButton() {
  const queryClient = useQueryClient();

  const handleRefresh = () => {
    queryClient.invalidateQueries({ queryKey: PROFILE_QUERY_KEY });
  };

  return <button onClick={handleRefresh}>Refresh Profile</button>;
}
```

## 处理错误

SDK提供了一个 `ApiError` 结构化错误处理的分类 :

```tsx
import { ApiError, isApiError } from "@fluid-app/portal-sdk";

try {
  await someApiCall();
} catch (error) {
  if (isApiError(error)) {
    console.log("Status:", error.status);
    console.log("Message:", error.message);
    console.log("Data:", error.data); // Server error details
  }
}
```

## 许可证

私营企业-流体商业

## 常见问题

### @fluid-app/portal-sdk 是什么？

用于自定义 Fluid 门户的 SDK

### 如何安装 @fluid-app/portal-sdk？

在项目目录运行 npm install @fluid-app/portal-sdk，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：zod（4\.6\.5）、react（^19\.2\.4）、react-dom（^19\.2\.4）、lucide-react（~0\.575\.0）、react-hook-form（^7\.64\.0）、@hookform/resolvers（^5\.2\.2）、@tanstack/react-query（^5\.90\.11）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @fluid-app/portal-sdk 支持 TypeScript 吗？

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

### @fluid-app/portal-sdk 支持 ESM 还是 CommonJS？

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

### @fluid-app/portal-sdk 可以商用吗？

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

### @fluid-app/portal-sdk 的下载量有多少？

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

### @fluid-app/portal-sdk 还在维护吗？

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