버전: 10.x

useQuery()

비공식 베타 번역

이 페이지는 PageTurner AI로 번역되었습니다(베타). 프로젝트 공식 승인을 받지 않았습니다. 오류를 발견하셨나요? 문제 신고 →

참고

@trpc/react-query가 제공하는 훅은 @tanstack/react-query를 간단히 감싼 레이어입니다. 옵션과 사용 패턴에 대한 자세한 내용은 쿼리 문서를 참조하세요.

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 전용 옵션도 제공됩니다:

trpc.ssr: 전역 설정에서 ssr: true인 경우, 특정 쿼리에 대해 SSR을 비활성화하려면 false로 설정하세요. 전역 설정이 false일 때 프로시저 단위로 SSR을 활성화할 수는 없습니다.
trpc.abortOnUnmount: 전역 설정을 재정의하고 언마운트 시 쿼리 중단 여부를 선택합니다.
trpc.context: 링크에서 사용할 수 있는 추가 메타데이터를 추가합니다.

팁

입력값을 전달하지 않고 옵션만 설정해야 할 경우 undefined를 전달할 수 있습니다.

백엔드의 input 스키마 설정에 기반해 input에 대한 자동 완성 기능이 제공되는 것을 확인할 수 있습니다.

예시

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

예시​

예시