useQuery

tsx

const {
  data,
  dataUpdatedAt,
  error,
  errorUpdatedAt,
  failureCount,
  failureReason,
  fetchStatus,
  isError,
  isFetched,
  isFetchedAfterMount,
  isFetching,
  isInitialLoading,
  isLoading,
  isLoadingError,
  isPaused,
  isPending,
  isPlaceholderData,
  isRefetchError,
  isRefetching,
  isStale,
  isSuccess,
  isEnabled,
  promise,
  refetch,
  status,
} = useQuery(
  {
    queryKey,
    queryFn,
    gcTime,
    enabled,
    networkMode,
    initialData,
    initialDataUpdatedAt,
    meta,
    notifyOnChangeProps,
    placeholderData,
    queryKeyHashFn,
    refetchInterval,
    refetchIntervalInBackground,
    refetchOnMount,
    refetchOnReconnect,
    refetchOnWindowFocus,
    retry,
    retryOnMount,
    retryDelay,
    select,
    staleTime,
    structuralSharing,
    subscribed,
    throwOnError,
  },
  queryClient,
)

const {
  data,
  dataUpdatedAt,
  error,
  errorUpdatedAt,
  failureCount,
  failureReason,
  fetchStatus,
  isError,
  isFetched,
  isFetchedAfterMount,
  isFetching,
  isInitialLoading,
  isLoading,
  isLoadingError,
  isPaused,
  isPending,
  isPlaceholderData,
  isRefetchError,
  isRefetching,
  isStale,
  isSuccess,
  isEnabled,
  promise,
  refetch,
  status,
} = useQuery(
  {
    queryKey,
    queryFn,
    gcTime,
    enabled,
    networkMode,
    initialData,
    initialDataUpdatedAt,
    meta,
    notifyOnChangeProps,
    placeholderData,
    queryKeyHashFn,
    refetchInterval,
    refetchIntervalInBackground,
    refetchOnMount,
    refetchOnReconnect,
    refetchOnWindowFocus,
    retry,
    retryOnMount,
    retryDelay,
    select,
    staleTime,
    structuralSharing,
    subscribed,
    throwOnError,
  },
  queryClient,
)

参数1 (Options)

queryKey: unknown[]
- 必需
- 用于此查询的查询键。
- 查询键将被哈希为一个稳定的哈希值。有关更多信息，请参阅查询键。
- 只要 enabled 没有被设置为 false，查询就会在此键更改时自动更新。
queryFn: (context: QueryFunctionContext) => Promise<TData>
- 必需，但仅在未定义默认查询函数时需要 有关更多信息，请参阅默认查询函数。
- 查询将用于请求数据的函数。
- 接收 QueryFunctionContext
- 必须返回一个解析数据或抛出错误的 Promise。数据不能是 undefined。
enabled: boolean | (query: Query) => boolean
- 将其设置为 false 以禁用此查询的自动运行。
- 可用于依赖查询。
networkMode: 'online' | 'always' | 'offlineFirst'
- 可选
- 默认为 'online'
- 有关更多信息，请参阅网络模式。
retry: boolean | number | (failureCount: number, error: TError) => boolean
- 如果设置为 false，失败的查询默认将不会重试。
- 如果设置为 true，失败的查询将无限重试。
- 如果设置为一个 number，例如 3，失败的查询将重试，直到失败查询计数达到该数字。
- 在客户端上默认为 3，在服务器上默认为 0
retryOnMount: boolean
- 如果设置为 false，则包含错误的查询在挂载时不会重试。默认为 true。
retryDelay: number | (retryAttempt: number, error: TError) => number
- 此函数接收一个 retryAttempt 整数和实际的错误，并返回在下次尝试之前应用的延迟（以毫秒为单位）。
- 像 attempt => Math.min(attempt > 1 ? 2 ** attempt * 1000 : 1000, 30 * 1000) 这样的函数会应用指数退避。
- 像 attempt => attempt * 1000 这样的函数会应用线性退避。
staleTime: number | 'static' | ((query: Query) => number | 'static')
- Optional (可选)
- 默认为 0
- 数据被视为过时之前的时间（以毫秒为单位）。此值仅适用于定义它的 hook。
- 如果设置为 Infinity，除非手动使数据失效，否则数据不会被视为过时。
- 如果设置为一个函数，该函数将使用查询进行执行，以计算 staleTime。
- 如果设置为 'static'，数据将永远不会被视为过时。
gcTime: number | Infinity
- 默认为 5 * 60 * 1000（5 分钟）或服务器端渲染期间的 Infinity。
- 未使用的/非活动缓存数据在内存中保留的时间（以毫秒为单位）。当查询的缓存变得无用或非活动时，该缓存数据将在该持续时间后被垃圾回收。当指定了不同的垃圾回收时间时，将使用最长的时间。
- 注意：允许的最大时间约为 24 天，尽管可以通过 timeoutManager.setTimeoutProvider 来规避此限制。
- 如果设置为 Infinity，将禁用垃圾回收。
queryKeyHashFn: (queryKey: QueryKey) => string
- Optional (可选)
- 如果指定，此函数将用于将 queryKey 哈希为一个字符串。
refetchInterval: number | false | ((query: Query) => number | false | undefined)
- Optional (可选)
- 如果设置为一个数字，所有查询将以该频率（以毫秒为单位）连续重新获取。
- 如果设置为一个函数，该函数将使用查询进行执行，以计算频率。
refetchIntervalInBackground: boolean
- Optional (可选)
- 如果设置为 true，则具有 refetchInterval 设置的查询将继续在标签页/窗口处于后台时重新获取。
refetchOnMount: boolean | "always" | ((query: Query) => boolean | "always")
- Optional (可选)
- 默认为 true
- 如果设置为 true，如果数据已过时，则查询将在挂载时重新获取。
- 如果设置为 false，则查询在挂载时不会重新获取。
- 如果设置为 "always"，则查询将在挂载时始终重新获取（除非使用了 staleTime: 'static'）。
- 如果设置为函数，该函数将使用查询进行执行，以计算值。
refetchOnWindowFocus: boolean | "always" | ((query: Query) => boolean | "always")
- Optional (可选)
- 默认为 true
- 如果设置为 true，如果数据已过时，则查询将在窗口聚焦时重新获取。
- 如果设置为 false，则查询在窗口聚焦时不会重新获取。
- 如果设置为 "always"，则查询将在窗口聚焦时始终重新获取（除非使用了 staleTime: 'static'）。
- 如果设置为函数，该函数将使用查询进行执行，以计算值。
refetchOnReconnect: boolean | "always" | ((query: Query) => boolean | "always")
- Optional (可选)
- 默认为 true
- 如果设置为 true，如果数据已过时，则查询将在重新连接时重新获取。
- 如果设置为 false，则查询在重新连接时不会重新获取。
- 如果设置为 "always"，则查询将在重新连接时始终重新获取（除非使用了 staleTime: 'static'）。
- 如果设置为函数，该函数将使用查询进行执行，以计算值。
notifyOnChangeProps: string[] | "all" | (() => string[] | "all" | undefined)
- Optional (可选)
- 如果设置，组件将仅在列出的任何属性更改时重新渲染。
- 例如，如果设置为 ['data', 'error']，则组件仅在 data 或 error 属性更改时重新渲染。
- 如果设置为 "all"，组件将选择退出智能跟踪，并在每次查询更新时重新渲染。
- 如果设置为函数，该函数将执行以计算属性列表。
- 默认情况下，属性的访问将被跟踪，组件仅在跟踪的任何属性更改时重新渲染。
select: (data: TData) => unknown
- Optional (可选)
- 此选项可用于转换或选择查询函数返回的数据的一部分。它会影响返回的 data 值，但不会影响存储在查询缓存中的内容。
- select 函数仅在 data 更改时，或 select 函数本身的引用更改时运行。为了优化，请将函数包装在 useCallback 中。
initialData: TData | () => TData
- Optional (可选)
- 如果设置，此值将用作查询缓存的初始数据（只要查询尚未创建或缓存）。
- 如果设置为函数，该函数将在共享/根查询初始化期间 **仅调用一次**，并期望同步返回 initialData。
- 默认情况下，除非设置了 staleTime，否则初始数据将被视为过时。
- initialData **会被持久化**到缓存中。
initialDataUpdatedAt: number | (() => number | undefined)
- Optional (可选)
- 如果设置，此值将用作 initialData 本身最后更新时间的时间戳（以毫秒为单位）。
placeholderData: TData | (previousValue: TData | undefined, previousQuery: Query | undefined) => TData
- Optional (可选)
- 如果设置，此值将用作此特定查询观察者在查询仍处于 pending 状态期间的占位符数据。
- placeholderData **不会被持久化**到缓存中。
- 如果您为 placeholderData 提供一个函数，第一个参数将接收先前观察到的查询数据（如果可用），第二个参数将是完整的 previousQuery 实例。
structuralSharing: boolean | (oldData: unknown | undefined, newData: unknown) => unknown
- Optional (可选)
- 默认为 true
- 如果设置为 false，将禁用查询结果之间的结构化共享。
- 如果设置为一个函数，旧数据和新数据值将通过此函数传递，该函数应将它们合并为查询的解析数据。这样，您就可以保留旧数据的引用以提高性能，即使这些数据包含不可序列化的值。
subscribed: boolean
- Optional (可选)
- 默认为 true
- 如果设置为 false，此 useQuery 实例将不会订阅缓存。这意味着它不会自行触发 queryFn，并且如果数据通过其他方式进入缓存，它也不会收到更新。
throwOnError: undefined | boolean | (error: TError, query: Query) => boolean
- 如果您希望错误在渲染阶段抛出并传播到最近的错误边界，请将其设置为 true。
- 要禁用 suspense 默认的将错误抛出到错误边界的行为，请将其设置为 false。
- 如果设置为一个函数，它将接收错误和查询，并应返回一个布尔值，指示是显示错误到错误边界（true）还是将错误作为状态返回（false）。
meta: Record<string, unknown>
- Optional (可选)
- 如果设置，将在查询缓存条目上存储附加信息，可根据需要使用。它可以在查询可用的任何地方访问，并且也是提供给 queryFn 的 QueryFunctionContext 的一部分。

参数2 (QueryClient)

queryClient?: QueryClient
- 使用此选项可以使用自定义 QueryClient。否则，将使用最近上下文中的 QueryClient。

Returns (返回)

status: QueryStatus
- 将是
  - pending，如果还没有缓存数据并且还没有完成查询尝试。
  - error，如果查询尝试导致错误。相应的 error 属性是尝试获取时收到的错误。
  - success，如果查询已收到无错误的响应并且已准备好显示其数据。查询上相应的 data 属性是成功获取的数据，或者如果查询的 enabled 属性设置为 false 且尚未获取，则 data 是在初始化时提供给查询的第一个 initialData。
isPending: boolean
- 来自上面 status 变量的派生布尔值，为了方便起见提供。
isSuccess: boolean
- 来自上面 status 变量的派生布尔值，为了方便起见提供。
isError: boolean
- 来自上面 status 变量的派生布尔值，为了方便起见提供。
isLoadingError: boolean
- 如果查询在首次获取时失败，此值为 true。
isRefetchError: boolean
- 如果查询在重新获取时失败，此值为 true。
data: TData
- 默认为 undefined。
- 查询的最后一个成功解析的数据。
dataUpdatedAt: number
- 查询最近一次返回 status 为 "success" 的时间戳。
error: null | TError
- 默认为 null。
- 如果抛出了错误，则为查询的错误对象。
errorUpdatedAt: number
- 查询最近一次返回 status 为 "error" 的时间戳。
isStale: boolean
- 如果缓存中的数据已失效或数据比给定的 staleTime 旧，此值为 true。
isPlaceholderData: boolean
- 如果显示的数据是占位符数据，此值为 true。
isFetched: boolean
- 如果查询已被获取，此值为 true。
isFetchedAfterMount: boolean
- 如果查询在组件挂载后已被获取，此值为 true。
- 此属性可用于不显示任何先前缓存的数据。
fetchStatus: FetchStatus
- fetching：当 queryFn 执行时为 true，包括初始 pending 和后台重新获取。
- paused：查询需要获取，但已被 paused。
- idle：查询未在获取。
- 有关更多信息，请参阅网络模式。
isFetching: boolean
- 来自上面 fetchStatus 变量的派生布尔值，为了方便起见提供。
isPaused: boolean
- 来自上面 fetchStatus 变量的派生布尔值，为了方便起见提供。
isRefetching: boolean
- 当后台重新获取正在进行中时为 true，这**不包括**初始 pending。
- 等同于 isFetching && !isPending。
isLoading: boolean
- 当查询的首次获取正在进行中时为 true。
- 等同于 isFetching && isPending。
isInitialLoading: boolean
- 已弃用
- isLoading 的别名，将在下一个主要版本中移除。
isEnabled: boolean
- 如果此查询观察者已启用，则为 true，否则为 false。
failureCount: number
- 查询的失败计数。
- 每次查询失败时递增。
- 当查询成功时重置为 0。
failureReason: null | TError
- 查询重试的失败原因。
- 当查询成功时重置为 null。
errorUpdateCount: number
- 所有错误的总和。
refetch: (options: { throwOnError: boolean, cancelRefetch: boolean }) => Promise<UseQueryResult>
- 手动重新获取查询的函数。
- 如果查询出错，错误只会记录下来。如果您希望抛出错误，请传递 throwOnError: true 选项。
- cancelRefetch?: boolean
  - 默认为 true
    - 默认情况下，当前正在进行的请求将在新请求之前被取消。
  - 当设置为 false 时，如果已有请求正在进行，则不会进行重新获取。
promise: Promise<TData>
- 一个稳定的 Promise，将使用查询的数据进行解析。
- 需要在 QueryClient 上启用 experimental_prefetchInRender 功能标志。

想跳过文档吗？

想跳过文档吗？