useQuery
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[]必需
用于标识此查询的键。
查询键将被哈希为一个稳定字符串。详见 查询键（Query Keys）。
当此键发生变化时（且
enabled不为false），查询会自动重新执行。
queryFn: (context: QueryFunctionContext) => Promise<TData>必需，除非已定义了默认查询函数（见默认查询函数）
查询用于请求数据的函数。
接收一个 QueryFunctionContext 参数。
必须返回一个 Promise，该 Promise 要么解析出数据，要么抛出错误。数据不能为
undefined。
enabled: boolean | (query: Query) => boolean设为
false可阻止查询自动运行。常用于实现依赖查询（Dependent Queries）。
networkMode: 'online' | 'always' | 'offlineFirst'可选
默认值：
'online'更多信息见 网络模式（Network Mode）。
retry: boolean | number | (failureCount: number, error: TError) => boolean若为
false，失败的查询将不会重试。若为
true，失败的查询将无限次重试。若设为数字（如
3），则最多重试指定次数。默认值：客户端为
3，服务端为0。
retryOnMount: boolean若设为
false，组件挂载时即使有错误也不会重试查询。默认为true。
retryDelay: number | (retryAttempt: number, error: TError) => number接收重试次数和错误对象，返回下次重试前的延迟时间（毫秒）。
示例：
指数退避：
attempt => Math.min(attempt > 1 ? 2 ** attempt * 1000 : 1000, 30 * 1000)线性退避：
attempt => attempt * 1000
staleTime: number | 'static' | ((query: Query) => number | 'static')可选，默认值：
0数据被视为“过期”的毫秒时间。仅对当前 hook 生效。
若为
Infinity，数据永不视为过期（除非手动失效）。若为
'static'，数据永不视为过期。若为函数，则传入
query对象以动态计算staleTime。
gcTime: number | Infinity默认值：
5 * 60 * 1000（5 分钟），SSR 期间为Infinity未使用或非活跃缓存数据在内存中保留的时间（毫秒）。当缓存变为非活跃状态后，将在该时间后被垃圾回收。
注意：最大允许时间为约 24 天，但可通过 timeoutManager.setTimeoutProvider 绕过限制。
若设为
Infinity，则禁用垃圾回收。
queryKeyHashFn: (queryKey: QueryKey) => string可选
自定义查询键的哈希函数。
refetchInterval: number | false | ((query: Query) => number | false | undefined)可选
若为数字，查询将按该毫秒频率持续轮询。
若为函数，则传入
query对象以动态计算轮询频率。
refetchIntervalInBackground: boolean可选
若为
true，即使页面处于后台标签页，也会继续按refetchInterval轮询。
refetchOnMount: boolean | "always" | ((query: Query) => boolean | "always")可选，默认值：
truetrue：若数据已过期，组件挂载时重新获取。false：不重新获取。"always"：总是重新获取（除非staleTime: 'static'）。函数形式：传入
query计算返回值。
refetchOnWindowFocus: boolean | "always" | ((query: Query) => boolean | "always")可选，默认值：
truetrue：窗口获得焦点且数据过期时重新获取。false：不重新获取。"always"：总是重新获取（除非staleTime: 'static'）。函数形式：传入
query计算返回值。
refetchOnReconnect: boolean | "always" | ((query: Query) => boolean | "always")可选，默认值：
truetrue：网络重连且数据过期时重新获取。false：不重新获取。"always"：总是重新获取（除非staleTime: 'static'）。函数形式：传入
query计算返回值。
notifyOnChangeProps: string[] | "all" | (() => string[] | "all" | undefined)可选
若设置，组件仅在指定属性变化时才重新渲染。
例如
['data', 'error']：仅当data或error变化时更新。"all"：关闭智能追踪，任何查询更新都触发渲染。函数形式：动态生成属性列表。
默认行为：自动追踪访问的属性，仅在其变化时重新渲染。
select: (data: TData) => unknown可选
用于转换或选择部分数据。影响返回的
data，但不影响缓存中的原始数据。select函数仅在data改变或其自身引用改变时执行。建议使用useCallback优化。
initialData: TData | () => TData可选
若设置，将作为查询缓存的初始数据（前提是该查询尚未创建或缓存）。
若为函数，会在共享/根查询初始化时同步调用一次。
初始数据默认是“过期”的，除非设置了
staleTime。initialData会被持久化到缓存中。
initialDataUpdatedAt: number | (() => number | undefined)可选
表示
initialData最后一次更新的时间戳（毫秒）。
placeholderData: TData | (previousValue: TData | undefined, previousQuery: Query | undefined) => TData可选
在查询处于
pending状态时，作为占位数据使用。placeholderData不会被持久化到缓存中。若为函数，第一个参数是之前查询的数据（如有），第二个是之前的
query实例。
structuralSharing: boolean | (oldData: unknown | undefined, newData: unknown) => unknown可选，默认值：
true若为
false，则禁用结构共享。若为函数，传入新旧数据，返回合并后的结果。可用于保留旧数据引用以提升性能。
subscribed: boolean可选，默认值：
true若为
false，此useQuery实例将不订阅缓存，即不会主动触发queryFn，也不会接收其他方式写入缓存的数据更新。
throwOnError: undefined | boolean | (error: TError, query: Query) => booleantrue：在渲染阶段抛出错误，传递给最近的错误边界。false：禁用 Suspense 的错误抛出行为，错误作为状态返回。函数形式：决定是否将错误抛向错误边界（
true）还是作为状态处理（false）。
meta: Record<string, unknown>可选
存储额外元信息，可在
query可用处访问，也包含在QueryFunctionContext中。
参数2（QueryClient）
queryClient?: QueryClient用于指定自定义的
QueryClient实例。若未提供，则使用最近上下文中的QueryClient。
返回值（Returns）
status: QueryStatus查询状态：
pending：无缓存数据且尚未完成首次请求。error：请求失败。对应的error属性包含错误对象。success：请求成功，可展示数据。对应的data属性为成功获取的数据；若enabled为false且未请求过，data为初始化时传入的initialData。
isPending: boolean根据
status派生的布尔值，表示是否处于pending状态。
isSuccess: boolean表示是否处于
success状态。
isError: boolean表示是否处于
error状态。
isLoadingError: boolean首次获取数据失败时为
true。
isRefetchError: boolean后续刷新数据失败时为
true。
data: TData默认为
undefined。最近一次成功获取的数据。
dataUpdatedAt: number上次查询状态变为
"success"的时间戳。
error: null | TError默认为
null。查询失败时的错误对象。
errorUpdatedAt: number上次查询状态变为
"error"的时间戳。
isStale: boolean若缓存数据已被标记为无效或超过
staleTime，则为true。
isPlaceholderData: boolean若当前显示的是占位数据，则为
true。
isFetched: boolean若查询已被获取过，则为
true。
isFetchedAfterMount: boolean若组件挂载后查询已被获取，则为
true。可用于避免显示挂载前的缓存数据。
fetchStatus: FetchStatusfetching：queryFn正在执行（包括首次加载和后台刷新）。paused：本应获取，但因网络等原因暂停。idle：未在获取。
isFetching: boolean根据
fetchStatus派生，表示是否正在获取。
isPaused: boolean表示是否处于暂停状态。
isRefetching: boolean后台刷新进行中时为
true（不包括首次加载）。等价于
isFetching && !isPending。
isLoading: boolean首次获取数据进行中时为
true。等价于
isFetching && isPending。
isInitialLoading: boolean已弃用
isLoading的别名，将在下一主要版本中移除。
isEnabled: boolean若此查询观察者已启用，则为
true。
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实验性功能标志才可用。
注意：本文档基于 React Query 的 API 设计，适用于 v4 或更高版本。具体行为请参考官方文档及实际项目配置。
最后更新于
这有帮助吗？