React SDK

React SDK 是一个纯粹的、强类型的前端表示层，它建立在底层的 Ontology SDK 之上。

它的核心设计理念是：结合 @tanstack/react-query 提供开箱即用的缓存、Suspense（悬停加载）、乐观更新（Optimistic Updates）以及与后端WebSocket 的无缝同步。目标是为你提供零样板代码的数据密集型 UI 开发体验。

1. 全局提供者 (OsdkProvider)

在应用的入口，你需要包裹 OsdkProvider。它会在内部为你配置好 React Query，并自动建立 WebSocket 连接。当后端本体数据发生变更时，它会自动刷新前端对应的缓存数据，实现“多人协作实时刷新”的效果。

import { OsdkProvider } from "@loambase/osdk-react";
import { client } from "./.osdk/client"; // 这是你通过 CLI 生成的 client
 
export default function App({ children }) {
  return (
    <OsdkProvider client={client}>
      {children}
    </OsdkProvider>
  );
}

2. 强类型的数据读取 (Read Hooks)

代码生成器会为你平台上的每一个本体对象生成专属的 React Hook（如 useCustomer, useOrders）。

2.1 单对象获取

import { useCustomer } from "@loambase/osdk-react/generated";
 
const CustomerProfile = ({ customerId }) => {
  // data 的类型会自动推导为 Customer 对象
  const { data: customer, isLoading } = useCustomer(customerId);
 
  if (isLoading) return <Spinner />;
  return <h1>{customer.properties.name}</h1>;
};

2.2 列表与分页搜索

支持传入过滤条件，并自动处理游标分页（Cursor Pagination）。

import { useOrders } from "@loambase/osdk-react/generated";
 
const CustomerOrders = ({ customerId }) => {
  const { data: ordersPage } = useOrders({ 
    filters: { customerId: customerId },
    pageSize: 20
  });
 
  return (
    <ul>
      {ordersPage.data.map(order => (
        <li key={order.$primaryKey}>{order.properties.status}</li>
      ))}
    </ul>
  );
};

3. 强类型的动作触发 (Mutation Hooks)

针对你在平台上定义的 Action，SDK 同样会生成对应的 Mutation Hook。

最强大的一点是：生成的 Hook 已经内置了乐观更新（Optimistic Update）逻辑。当你点击按钮时，UI 会瞬间变成成功状态，即使用户的网络很慢。如果后端报错，UI 会自动回滚。

import { useApproveOrder } from "@loambase/osdk-react/generated";
 
const OrderAction = ({ order }) => {
  // 这个 Hook 已经封装了 React Query 的 useMutation
  const approveMutation = useApproveOrder();
 
  return (
    <button 
      onClick={() => approveMutation.mutate({ orderId: order.$primaryKey })}
      disabled={approveMutation.isPending}
    >
      {approveMutation.isPending ? "Approving..." : "Approve"}
    </button>
  );
};

4. 通用图谱探索 Hooks

如果你在做一个通用的搜索框或者知识图谱探索页面，编译期无法知道具体的对象类型，可以使用 SDK 提供的通用 Hooks。

4.1 全局搜索

import { useObjectSearch } from "@loambase/osdk-react";
 
// 在指定的 ObjectType 下进行全文关键字搜索
const { data } = useObjectSearch("Employee", "John");

4.2 图谱漫游 (Graph Traversal)

获取某个对象及其向外辐射 2 层深度的所有关联对象。

import { useOntologyGraph } from "@loambase/osdk-react";
 
// 获取订单，以及关联的客户、明细行
const { data: graph } = useOntologyGraph("Order", "ORD-123", 2);

Platform SDK (基础底座)Agent SDK (AI 集成)