useQuery()

注意

@trpc/react-query 提供的钩子是 @tanstack/react-query 的薄封装。有关选项和使用模式的深入信息，请参阅 queries 上的文档。

¥The hooks provided by @trpc/react-query are a thin wrapper around @tanstack/react-query. For in-depth information about options and usage patterns, refer to their docs on queries.

tsx
function useQuery(
  input: TInput,
  opts?: UseTRPCQueryOptions;
)
interface UseTRPCQueryOptions
  extends UseQueryOptions {
  trpc: {
    ssr?: boolean;
    abortOnUnmount?: boolean;
    context?: Record<string, unknown>;
  }
}

tsx
function useQuery(
  input: TInput,
  opts?: UseTRPCQueryOptions;
)
interface UseTRPCQueryOptions
  extends UseQueryOptions {
  trpc: {
    ssr?: boolean;
    abortOnUnmount?: boolean;
    context?: Record<string, unknown>;
  }
}

由于 UseTRPCQueryOptions 扩展了 @tanstack/react-query 的 UseQueryOptions，因此你可以在此处使用它们的任何选项，例如 enabled、refetchOnWindowFocus 等。我们还有一些 trpc 特定选项，可让你在每个过程级别上选择加入或退出某些行为 ：

¥Since UseTRPCQueryOptions extends @tanstack/react-query's UseQueryOptions, you can use any of their options here such as enabled, refetchOnWindowFocus, etc. We also have some trpc specific options that let you opt in or out of certain behaviors on a per-procedure level:

• trpc.ssr：如果 全局配置 中有 ssr: true，则可以将其设置为 false 以禁用此特定查询的 ssr。请注意，反之则不行，即，如果你的全局配置设置为 false，则无法在过程上启用 ssr。

  ¥trpc.ssr: If you have ssr: true in your global config, you can set this to false to disable ssr for this particular query. Note that this does not work the other way around, i.e., you can not enable ssr on a procedure if your global config is set to false.

• trpc.abortOnUnmount：覆盖 全局配置 并选择在卸载时中止查询。

  ¥trpc.abortOnUnmount: Override the global config and opt in or out of aborting queries on unmount.

• trpc.context：添加可在 链接 中使用的额外元数据。

  ¥trpc.context: Add extra meta data that could be used in Links.

提示

如果你需要设置任何选项但不想传递任何输入，则可以传递 undefined。

¥If you need to set any options but don't want to pass any input, you can pass undefined instead.

你会注意到，你会根据你在后端 input 架构中设置的内容在 input 上获得自动补齐功能。

¥You'll notice that you get autocompletion on the input based on what you have set in your input schema on your backend.

示例

¥Example

Backend code

server/routers/_app.ts
tsx
import { initTRPC } from '@trpc/server';
import { z } from 'zod';
export const t = initTRPC.create();
export const appRouter = t.router({
  // Create procedure at path 'hello'
  hello: t.procedure
    // using zod schema to validate and infer input values
    .input(
      z
        .object({
          text: z.string().nullish(),
        })
        .nullish(),
    )
    .query((opts) => {
      return {
        greeting: `hello ${opts.input?.text ?? 'world'}`,
      };
    }),
});

server/routers/_app.ts
tsx
import { initTRPC } from '@trpc/server';
import { z } from 'zod';
export const t = initTRPC.create();
export const appRouter = t.router({
  // Create procedure at path 'hello'
  hello: t.procedure
    // using zod schema to validate and infer input values
    .input(
      z
        .object({
          text: z.string().nullish(),
        })
        .nullish(),
    )
    .query((opts) => {
      return {
        greeting: `hello ${opts.input?.text ?? 'world'}`,
      };
    }),
});

components/MyComponent.tsx
tsx
import { trpc } from '../utils/trpc';
export function MyComponent() {
  // input is optional, so we don't have to pass second argument
  const helloNoArgs = trpc.hello.useQuery();
  const helloWithArgs = trpc.hello.useQuery({ text: 'client' });
  return (
    <div>
      <h1>Hello World Example</h1>
      <ul>
        <li>
          helloNoArgs ({helloNoArgs.status}):{' '}
          <pre>{JSON.stringify(helloNoArgs.data, null, 2)}</pre>
        </li>
        <li>
          helloWithArgs ({helloWithArgs.status}):{' '}
          <pre>{JSON.stringify(helloWithArgs.data, null, 2)}</pre>
        </li>
      </ul>
    </div>
  );
}

components/MyComponent.tsx
tsx
import { trpc } from '../utils/trpc';
export function MyComponent() {
  // input is optional, so we don't have to pass second argument
  const helloNoArgs = trpc.hello.useQuery();
  const helloWithArgs = trpc.hello.useQuery({ text: 'client' });
  return (
    <div>
      <h1>Hello World Example</h1>
      <ul>
        <li>
          helloNoArgs ({helloNoArgs.status}):{' '}
          <pre>{JSON.stringify(helloNoArgs.data, null, 2)}</pre>
        </li>
        <li>
          helloWithArgs ({helloWithArgs.status}):{' '}
          <pre>{JSON.stringify(helloWithArgs.data, null, 2)}</pre>
        </li>
      </ul>
    </div>
  );
}