본문으로 건너뛰기

useQuery

호출 시그니처​

function useQuery<TQueryFnData, TError, TData, TQueryKey>(options, queryClient?): DefinedUseQueryResult<TData, TError>;

정의 위치: preact-query/src/useQuery.ts:50

initialData가 설정되면 이 오버로드가 선택되므로, 결과 data는 절대 undefined가 아닙니다.

타입 매개변수​

TQueryFnData​

TQueryFnData = unknown

TError​

TError = Error

TData​

TData = TQueryFnData

TQueryKey​

TQueryKey extends readonly unknown[] = readonly unknown[]

매개변수​

옵션​

DefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>

사용할 DefinedInitialDataOptions입니다. initialData가 설정된 상태로 useQuery에 전달할 수 있는 모든 항목을 포함합니다.

queryClient?​

QueryClient

사용자 지정 QueryClient를 사용하려면 이를 사용합니다. 그렇지 않으면 가장 가까운 컨텍스트의 항목이 사용됩니다 사용됩니다.

반환값​

DefinedUseQueryResult<TData, TError>

현재 쿼리 결과이며, status가 success가 되도록 타입이 지정됩니다 — 또는 가져오기 시도가 있었다면 error가 됩니다 기존 데이터를 유지하면서 실패합니다(이 오버로드의 타입에서 status는 절대로 pending으로 이행되지 않으며, initialData가 데이터를 미리 보장하기 때문입니다). isSuccess/isError는 편의를 위해 파생된 불리언 값입니다.

참조​

useQuery와 queryClient.query 같은 명령형 API 간에 이러한 옵션을 공유하려면 queryOptions를 사용합니다.

예시​

import { useQuery } from '@tanstack/preact-query'

function Posts() {
  // `data` is `Post[]`, never `undefined`, thanks to `initialData` — even if a refetch fails,
  // so the list stays visible alongside the error.
  const { data, isError, error } = useQuery({
    queryKey: ['posts'],
    queryFn: fetchPosts,
    initialData: [],
  })

  return (
    <div>
      {isError ? <span>Error: {error.message}</span> : null}
      <ul>
        {data.map((post) => <li key={post.id}>{post.title}</li>)}
      </ul>
    </div>
  )
}

호출 시그니처​

function useQuery<TQueryFnData, TError, TData, TQueryKey>(options, queryClient?): UseQueryResult<TData, TError>;

정의 위치: preact-query/src/useQuery.ts:119

타입 매개변수​

TQueryFnData​

TQueryFnData = unknown

TError​

TError = Error

TData​

TData = TQueryFnData

TQueryKey​

TQueryKey extends readonly unknown[] = readonly unknown[]

매개변수​

옵션​

UndefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>

사용할 UndefinedInitialDataOptions입니다 — useQuery에 전달할 수 있는 모든 항목입니다.

queryClient?​

QueryClient

사용자 지정 QueryClient를 사용하려면 이를 사용합니다. 그렇지 않으면 가장 가까운 컨텍스트의 항목이 사용됩니다 사용됩니다.

반환값​

UseQueryResult<TData, TError>

현재 쿼리 결과입니다. 캐시된 데이터가 없고 쿼리 시도도 없으면 status는 pending입니다 아직 완료되지 않았다면 해당 상태를, 쿼리 시도에서 오류가 발생했다면 error를, 쿼리에 제공할 데이터가 있다면 success를 표시합니다. isPending/isSuccess/isError는 편의를 위해 파생된 불리언 값입니다.

참조​

useQuery와 queryClient.query 같은 명령형 API 간에 이러한 옵션을 공유하려면 queryOptions를 사용합니다.

예시​

import { queryOptions, useQuery } from '@tanstack/preact-query'

const postsOptions = queryOptions({
  queryKey: ['posts'],
  queryFn: fetchPosts,
})

function Posts() {
  const { status, data, error, isFetching } = useQuery(postsOptions)

  if (status === 'pending') return 'Loading...'
  if (status === 'error') return <span>Error: {error.message}</span>

  return (
    <div>
      <ul>
        {data.map((post) => (
          <li key={post.id}>{post.title}</li>
        ))}
      </ul>
      <div>{isFetching ? 'Background Updating...' : ' '}</div>
    </div>
  )
}

동일한 쿼리에서 status 대신 isPending/isError를 확인합니다 — 더 읽기 좋은 쪽을 선택하세요:

import { useQuery } from '@tanstack/preact-query'

function Posts() {
  const { isPending, isError, data, error } = useQuery({
    queryKey: ['posts'],
    queryFn: fetchPosts,
  })

  if (isPending) return 'Loading...'
  if (isError) return <span>Error: {error.message}</span>

  return (
    <ul>
      {data.map((post) => <li key={post.id}>{post.title}</li>)}
    </ul>
  )
}

호출 시그니처​

function useQuery<TQueryFnData, TError, TData, TQueryKey>(options, queryClient?): UseQueryResult<TData, TError>;

정의 위치: preact-query/src/useQuery.ts:297

타입 매개변수​

TQueryFnData​

TQueryFnData = unknown

TError​

TError = Error

TData​

TData = TQueryFnData

TQueryKey​

TQueryKey extends readonly unknown[] = readonly unknown[]

매개변수​

옵션​

UseQueryOptions<TQueryFnData, TError, TData, TQueryKey>

사용할 UseQueryOptions입니다 — useQuery에 전달할 수 있는 모든 항목입니다.

queryClient?​

QueryClient

사용자 지정 QueryClient를 사용하려면 이를 사용합니다. 그렇지 않으면 가장 가까운 컨텍스트의 항목이 사용됩니다 사용됩니다.

반환값​

UseQueryResult<TData, TError>

현재 쿼리 결과입니다. 캐시된 데이터가 없고 쿼리 시도도 없으면 status는 pending입니다 아직 완료되지 않았다면 해당 상태를, 쿼리 시도에서 오류가 발생했다면 error를, 쿼리에 제공할 데이터가 있다면 success를 표시합니다. isPending/isSuccess/isError는 편의를 위해 파생된 불리언 값입니다.

참조​

useQuery와 queryClient.query 같은 명령형 API 간에 이러한 옵션을 공유하려면 queryOptions를 사용합니다.

예시​

import { queryOptions, useQuery } from '@tanstack/preact-query'

const postsOptions = queryOptions({
  queryKey: ['posts'],
  queryFn: fetchPosts,
})

function Posts() {
  const { status, data, error, isFetching } = useQuery(postsOptions)

  if (status === 'pending') return 'Loading...'
  if (status === 'error') return <span>Error: {error.message}</span>

  return (
    <div>
      <ul>
        {data.map((post) => (
          <li key={post.id}>{post.title}</li>
        ))}
      </ul>
      <div>{isFetching ? 'Background Updating...' : ' '}</div>
    </div>
  )
}

postId가 설정된 후에만 활성화되는 종속 쿼리 — isPending이 아닌 isLoading을 사용하여 다음을 수행합니다 쿼리가 비활성화된 동안에는 로딩 상태가 표시되지 않습니다:

import { useQuery } from '@tanstack/preact-query'

function Post({ postId }: { postId: number | undefined }) {
  const { data, isLoading, isError, error } = useQuery({
    queryKey: ['post', postId],
    queryFn: () => fetchPost(postId!),
    enabled: postId != null,
  })

  if (postId == null) return 'Select a post'
  if (isLoading) return 'Loading...'
  if (isError) return <span>Error: {error.message}</span>

  return <h1>{data?.title}</h1>
}

동일한 종속 쿼리를 타입 안전하게 사용할 수 있습니다: skipToken은 해당 항목 없이도 쿼리를 비활성화합니다 postId가 정의된 경우에만 queryFn이 호출되므로 위에서 non-null assertion을 사용합니다. queryFn이 skipToken인 동안에는 refetch가 작동하지 않습니다 — 다음의 경우 대신 enabled: false를 사용하세요 쿼리를 수동으로 실행해야 합니다:

import { skipToken, useQuery } from '@tanstack/preact-query'

function Post({ postId }: { postId: number | undefined }) {
  const { data, isLoading, isError, error } = useQuery({
    queryKey: ['post', postId],
    queryFn: postId != null ? () => fetchPost(postId) : skipToken,
  })

  if (postId == null) return 'Select a post'
  if (isLoading) return 'Loading...'
  if (isError) return <span>Error: {error.message}</span>

  return <h1>{data?.title}</h1>
}

로딩 상태를 건너뛰기 위해 이미 캐시된 목록에서 상세 쿼리의 초기 데이터를 설정합니다:

import { useQuery, useQueryClient } from '@tanstack/preact-query'

function Post({ postId }: { postId: number }) {
  const queryClient = useQueryClient()

  const { data, isError, error } = useQuery({
    queryKey: ['post', postId],
    queryFn: () => fetchPost(postId),
    initialData: () =>
      queryClient
        .getQueryData<Array<Post>>(['posts'])
        ?.find((post) => post.id === postId),
  })

  if (isError) return <span>Error: {error.message}</span>

  return <h1>{data?.title}</h1>
}

페이지가 매겨진 데이터에서 다음 페이지를 불러오는 동안 이전 페이지의 데이터를 계속 표시합니다:

import { keepPreviousData, useQuery } from '@tanstack/preact-query'
import { useState } from 'preact/hooks'

function Posts() {
  const [page, setPage] = useState(0)

  const { data, isPlaceholderData, isError, error } = useQuery({
    queryKey: ['posts', page],
    queryFn: () => fetchPosts(page),
    placeholderData: keepPreviousData,
  })

  if (isError) return <span>Error: {error.message}</span>

  return (
    <div>
      <ul>
        {data?.map((post) => <li key={post.id}>{post.title}</li>)}
      </ul>
      <button
        disabled={isPlaceholderData}
        onClick={() => setPage((old) => old + 1)}
      >
        Next Page
      </button>
    </div>
  )
}

마우스를 올릴 때 캐시를 워밍하여 <Post>를 클릭하는 즉시 데이터가 있도록 합니다. 다음이 필요합니다 queryOptions 팩토리를 사용하므로 훅과 명령형 호출이 동일한 캐시 항목을 공유합니다:

import { noop, queryOptions, useQuery, useQueryClient } from '@tanstack/preact-query'

const postOptions = (id: string) =>
  queryOptions({
    queryKey: ['post', id],
    queryFn: () => fetchPost(id),
  })

function Post({ id }: { id: string }) {
  const { data, isError, error } = useQuery(postOptions(id))
  if (isError) return <span>Error: {error.message}</span>
  return <h1>{data?.title}</h1>
}

function PostLink({ id, title }: { id: string; title: string }) {
  const queryClient = useQueryClient()

  return (
    <a
      href={`/posts/${id}`}
      onMouseEnter={() => queryClient.query(postOptions(id)).catch(noop)}
    >
      {title}
    </a>
  )
}