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

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

安装

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

同伴依赖关系

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

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

快速启动

用 FluidProvider数字 :

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

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

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主题

控制主题设置 :

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 (主题管理)

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 主题管理, 可以单独使用 :

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

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

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

类型

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

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

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

查询密钥

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

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 结构化错误处理的分类 :

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
  }
}

许可证

私营企业-流体商业