跳至主内容
版本：11.x

设置 React Query 集成

非官方测试版翻译

本页面由 PageTurner AI 翻译（测试版）。未经项目官方认可。 发现错误？ 报告问题 →

1. 安装依赖​

需要安装以下依赖项。

npm install @trpc/server @trpc/client @trpc/react-query @tanstack/react-query
AI 代理

若您使用 AI 编程代理，请安装 tRPC 技能以优化代码生成效果：

bash
npx @tanstack/intent@latest install
bash
npx @tanstack/intent@latest install

2. 导入你的 AppRouter​

非官方测试版翻译

本页面由 PageTurner AI 翻译（测试版）。未经项目官方认可。 发现错误？ 报告问题 →

将你的 AppRouter 类型导入客户端应用中。该类型包含了整个 API 的结构定义。

utils/trpc.ts
ts
import type { AppRouter } from '../server/router';
utils/trpc.ts
ts
import type { AppRouter } from '../server/router';
技巧

使用 import type 可以确保类型引用在编译时被剥离，避免无意中将服务端代码导入客户端。更多信息请参阅 TypeScript 文档。

3. 创建 tRPC hooks​

使用 createTRPCReact 根据你的 AppRouter 类型签名创建一组强类型的 React hooks。

utils/trpc.ts
ts
import { createTRPCReact } from '@trpc/react-query';
import type { AppRouter } from '../server/router';
 
export const trpc = createTRPCReact<AppRouter>();
utils/trpc.ts
ts
import { createTRPCReact } from '@trpc/react-query';
import type { AppRouter } from '../server/router';
 
export const trpc = createTRPCReact<AppRouter>();

4. 添加 tRPC providers​

创建 tRPC 客户端并将你的应用包裹在 tRPC Provider 中（如下所示）。你还需要设置并连接 React Query，其详细文档可供参考。

技巧

如果你的应用中已经使用了 React Query，应该复用现有的 QueryClient 和 QueryClientProvider。

App.tsx
tsx
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { httpBatchLink } from '@trpc/client';
import React, { useState } from 'react';
import { trpc } from './utils/trpc';
 
export function App() {
  const [queryClient] = useState(() => new QueryClient());
  const [trpcClient] = useState(() =>
    trpc.createClient({
      links: [
        httpBatchLink({
          url: 'http://localhost:3000/trpc',
 
          // You can pass any HTTP headers you wish here
          async headers() {
            return {
              authorization: getAuthCookie(),
            };
          },
        }),
      ],
    }),
  );
 
  return (
    <trpc.Provider client={trpcClient} queryClient={queryClient}>
      <QueryClientProvider client={queryClient}>
        {/* Your app here */}
      </QueryClientProvider>
    </trpc.Provider>
  );
}
App.tsx
tsx
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { httpBatchLink } from '@trpc/client';
import React, { useState } from 'react';
import { trpc } from './utils/trpc';
 
export function App() {
  const [queryClient] = useState(() => new QueryClient());
  const [trpcClient] = useState(() =>
    trpc.createClient({
      links: [
        httpBatchLink({
          url: 'http://localhost:3000/trpc',
 
          // You can pass any HTTP headers you wish here
          async headers() {
            return {
              authorization: getAuthCookie(),
            };
          },
        }),
      ],
    }),
  );
 
  return (
    <trpc.Provider client={trpcClient} queryClient={queryClient}>
      <QueryClientProvider client={queryClient}>
        {/* Your app here */}
      </QueryClientProvider>
    </trpc.Provider>
  );
}
备注

在创建 queryClient 和 TRPCClient 时使用 useState 而非在组件外部声明，是为了确保在使用 SSR 时每个请求都能获得独立的客户端实例。如果使用客户端渲染，则可以根据需要将它们移出。

5. 获取数据​

现在你可以使用 tRPC 的 React Query 集成来调用 API 上的查询和变更操作。

pages/IndexPage.tsx
tsx
import { trpc } from '../utils/trpc';
 
export default function IndexPage() {
  const userQuery = trpc.getUser.useQuery({ id: 'id_bilbo' });
  const userCreator = trpc.createUser.useMutation();
 
  return (
    <div>
      <p>{userQuery.data?.name}</p>
 
      <button onClick={() => userCreator.mutate({ name: 'Frodo' })}>
        Create Frodo
      </button>
    </div>
  );
}
pages/IndexPage.tsx
tsx
import { trpc } from '../utils/trpc';
 
export default function IndexPage() {
  const userQuery = trpc.getUser.useQuery({ id: 'id_bilbo' });
  const userCreator = trpc.createUser.useMutation();
 
  return (
    <div>
      <p>{userQuery.data?.name}</p>
 
      <button onClick={() => userCreator.mutate({ name: 'Frodo' })}>
        Create Frodo
      </button>
    </div>
  );
}