React Query Integration（经典版）

提示

这些是我们 '经典' React Query 集成的文档，虽然仍然受支持，但这不是使用 TanStack React Query 启动新 tRPC 项目的推荐方式。我们建议改用新的 TanStack React Query 集成。

¥These are the docs for our 'Classic' React Query integration, which (while still supported) is not the recommended way to start new tRPC projects with TanStack React Query. We recommend using the new TanStack React Query Integration instead.

tRPC 提供了与 React 的一流集成。从本质上讲，这只是非常流行的 @tanstack/react-query 的封装，因此我们建议你熟悉 React Query，因为他们的文档更深入地介绍了它的用法。

¥tRPC offers a first class integration with React. Under the hood this is simply a wrapper around the very popular @tanstack/react-query, so we recommend that you familiarise yourself with React Query, as their docs go in to much greater depth on its usage.

如果你正在使用 Next.js，我们建议你改用 我们与它的整合。

¥If you are using Next.js we recommend using our integration with that instead.

❓ Do I have to use an integration?

No! The integration is fully optional. You can use @tanstack/react-query using just a vanilla tRPC client, although then you'll have to manually manage query keys and do not get the same level of DX as when using the integration package.

utils/trpc.ts
ts
export const trpc = createTRPCClient<AppRouter>({
  links: [httpBatchLink({ url: 'YOUR_API_URL' })],
});

utils/trpc.ts
ts
export const trpc = createTRPCClient<AppRouter>({
  links: [httpBatchLink({ url: 'YOUR_API_URL' })],
});

components/PostList.tsx
tsx
function PostList() {
  const { data } = useQuery({
    queryKey: ['posts'],
    queryFn: () => trpc.post.list.query(),
  });
  data; // Post[]
  // ...
}

components/PostList.tsx
tsx
function PostList() {
  const { data } = useQuery({
    queryKey: ['posts'],
    queryFn: () => trpc.post.list.query(),
  });
  data; // Post[]
  // ...
}

tRPC React 查询集成

¥The tRPC React Query Integration

该库可以直接在 React 组件中使用

¥This library enables usage directly within React components

pages/IndexPage.tsx
tsx
import { trpc } from '../utils/trpc';
export default function IndexPage() {
  const helloQuery = trpc.hello.useQuery({ name: 'Bob' });
  const goodbyeMutation = trpc.goodbye.useMutation();
  return (
    <div>
      <p>{helloQuery.data?.greeting}</p>
      <button onClick={() => goodbyeMutation.mutate()}>Say Goodbye</button>
    </div>
  );
}

pages/IndexPage.tsx
tsx
import { trpc } from '../utils/trpc';
export default function IndexPage() {
  const helloQuery = trpc.hello.useQuery({ name: 'Bob' });
  const goodbyeMutation = trpc.goodbye.useMutation();
  return (
    <div>
      <p>{helloQuery.data?.greeting}</p>
      <button onClick={() => goodbyeMutation.mutate()}>Say Goodbye</button>
    </div>
  );
}

与普通 React 查询的差异

¥Differences to vanilla React Query

封装器为你抽象了 React Query 的一些方面：

¥The wrapper abstracts some aspects of React Query for you:

• 查询键 - 这些是由 tRPC 根据你提供的过程输入代表你生成和管理的

  ¥Query Keys - these are generated and managed by tRPC on your behalf, based on the procedure inputs you provide

  • 如果需要 tRPC 计算的查询 key，可以使用 getQueryKey

    ¥If you need the query key which tRPC calculates, you can use getQueryKey

• 默认类型安全 - 你在 tRPC 后端中提供的类型也会驱动 React Query 客户端的类型，从而为整个 React 应用提供安全性

  ¥Type safe by default - the types you provide in your tRPC Backend also drive the types of your React Query client, providing safety throughout your React app