useQuery()

Traducción Beta No Oficial

Esta página fue traducida por PageTurner AI (beta). No está respaldada oficialmente por el proyecto. ¿Encontraste un error? Reportar problema →

useQuery es el hook principal para obtener datos. Funciona de manera similar al useQuery de @tanstack/react-query, pero con opciones específicas de trpc y características adicionales como streaming.

nota

Para información detallada sobre opciones y patrones de uso, consulta la documentación de TanStack Query sobre queries.

Firma

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

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

Como UseTRPCQueryOptions extiende UseQueryOptions de @tanstack/react-query, puedes usar cualquiera de sus opciones como enabled, refetchOnWindowFocus, etc. También tenemos opciones específicas de trpc que te permiten activar o desactivar comportamientos a nivel de procedimiento:

• trpc.ssr: Si tienes ssr: true en tu configuración global, puedes establecer esto en false para desactivar SSR para esta consulta específica. Nota que esto no funciona al revés, es decir, no puedes activar SSR en un procedimiento si tu configuración global está en false.

• trpc.abortOnUnmount: Anula la configuración global y activa o desactiva la cancelación de consultas al desmontar.

• trpc.context: Añade metadatos adicionales que podrían usarse en Links.

consejo

Si necesitas establecer opciones pero no quieres pasar ningún input, puedes pasar undefined.

Notarás que obtienes autocompletado para el input basado en lo que has configurado en tu esquema de input en el backend.

Ejemplo de uso

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'}`,
      };
    }),
});
 
export type AppRouter = typeof appRouter;

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'}`,
      };
    }),
});
 
export type AppRouter = typeof appRouter;

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

Respuestas en streaming usando generadores asíncronos

información

Desde la v11 admitimos consultas con streaming cuando usamos httpBatchStreamLink.

Cuando devuelves un generador asíncrono en una consulta, ocurrirá lo siguiente:

• Recibirás los resultados del iterador en la propiedad data como un array que se actualiza durante la respuesta

• El status será success al recibir el primer fragmento

• La propiedad fetchStatus permanecerá como fetching hasta recibir el último fragmento

Ejemplo

server/routers/_app.ts
tsx
import { initTRPC } from '@trpc/server';
 
const t = initTRPC.create();
 
const appRouter = t.router({
  iterable: t.procedure.query(async function* () {
    for (let i = 0; i < 3; i++) {
      await new Promise((resolve) => setTimeout(resolve, 500));
      yield i;
    }
  }),
});
 
export type AppRouter = typeof appRouter;

server/routers/_app.ts
tsx
import { initTRPC } from '@trpc/server';
 
const t = initTRPC.create();
 
const appRouter = t.router({
  iterable: t.procedure.query(async function* () {
    for (let i = 0; i < 3; i++) {
      await new Promise((resolve) => setTimeout(resolve, 500));
      yield i;
    }
  }),
});
 
export type AppRouter = typeof appRouter;

components/MyComponent.tsx
tsx
import React, { Fragment } from 'react';
import { trpc } from '../utils/trpc';
 
export function MyComponent() {
  const result = trpc.iterable.useQuery();
 
  return (
    <div>
      {result.data?.map((chunk, index) => (
        <Fragment key={index}>{chunk}</Fragment>
      ))}
    </div>
  );
}

components/MyComponent.tsx
tsx
import React, { Fragment } from 'react';
import { trpc } from '../utils/trpc';
 
export function MyComponent() {
  const result = trpc.iterable.useQuery();
 
  return (
    <div>
      {result.data?.map((chunk, index) => (
        <Fragment key={index}>{chunk}</Fragment>
      ))}
    </div>
  );
}

Propiedades de result durante el streaming:

status	fetchStatus	data
'pending'	'fetching'	undefined
'success'	'fetching'	[]
'success'	'fetching'	[0]
'success'	'fetching'	[0, 1]
'success'	'fetching'	[0, 1, 2]
'success'	'idle'	[0, 1, 2]