QueryClient

更新于 2026-11-02 Solid 查看英文原文 ↗

定义于：packages/solid-query/src/QueryClient.ts:117

核心 @tanstack/query-core QueryClient，其类型已声明为支持 Solid 的 reconcile 选项。

继承自

QueryClient

构造函数

TypeScript

1new QueryClient(config?: QueryClientConfig): QueryClient;

定义于：packages/solid-query/src/QueryClient.ts:118

参数

config?

QueryClientConfig = {}

返回值

QueryClient

覆盖

TypeScript

1QueryCoreClient.constructor

方法

cancelQueries()

TypeScript

1cancelQueries<TTaggedQueryKey extends readonly unknown[] = readonly unknown[]>(filters?: QueryFilters<TTaggedQueryKey>, cancelOptions?: CancelOptions): Promise<void>;

定义位置：packages/query-core/src/queryClient.ts:462

取消匹配给定筛选条件的查询的正在进行中的拉取操作。该方法在执行乐观更新时最为有用，因为否则任何后续解析的后台重新拉取操作都会覆盖乐观更新的结果。默认情况下（revert: true），被取消查询的数据会回滚至该次拉取开始前的状态。

即使个别取消操作失败，返回的 Promise 也永远不会被拒绝。

类型参数

TTaggedQueryKey

TTaggedQueryKey extends readonly unknown[] = readonly unknown[]

参数

filters?

QueryFilters<TTaggedQueryKey>

用于筛选待取消查询的过滤器。若不提供过滤器，则取消所有查询。

cancelOptions?

CancelOptions = {}

传递给每个匹配查询的取消操作。revert 默认为 true。

返回值

Promise<void>

一个 Promise，当所有取消操作均完成时即解析。

示例

TypeScript

1await queryClient.cancelQueries({ queryKey: ['posts'], exact: true })

继承自

TypeScript

1QueryCoreClient.cancelQueries

clear()

TypeScript

1clear(): void;

定义位置：packages/query-core/src/queryClient.ts:1172

清空此客户端所连接的查询缓存和修改缓存。

返回值

void

示例

TypeScript

1import { QueryClient } from '@tanstack/query-core'2 3const queryClient = new QueryClient()4queryClient.clear()

继承自

TypeScript

1QueryCoreClient.clear

defaultMutationOptions()

TypeScript

1defaultMutationOptions<T extends MutationOptions<any, any, any, any>>(options?: T): T;

定义位置：packages/query-core/src/queryClient.ts:1147

QueryClient#defaultQueryOptions 的对应修改版本。由框架适配器（例如在 useMutation 内部）调用，以合并客户端自身的 defaultOptions.mutations，然后合并针对给定 mutationKey 的 queryClient.setMutationDefaults，最后再合并调用方传入的选项。若选项已默认化（_defaulted: true），则该方法不执行任何操作。

类型参数

T

T extends MutationOptions<any, any, any, any>

参数

options?

T

调用方传入的修改选项。

返回值

T

已默认化的选项。

继承自

TypeScript

1QueryCoreClient.defaultMutationOptions

defaultQueryOptions()

TypeScript

1defaultQueryOptions<TQueryFnData = unknown, TError = Error, TData = TQueryFnData, TQueryData = TQueryFnData, TQueryKey extends readonly unknown[] = readonly unknown[], TPageParam = never>(options: 2  | QueryObserverOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey, TPageParam>3| DefaultedQueryObserverOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>): DefaultedQueryObserverOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>;

定义位置：packages/query-core/src/queryClient.ts:1058

由框架适配器（例如在 useQuery 内部）调用，将调用方传入的选项解析为其最终的、已默认化的形式：先合并客户端自身的 defaultOptions.queries，再合并针对给定 queryKey 的 queryClient.setQueryDefaults，最后合并调用方的选项。若选项已默认化（_defaulted: true），则该方法不执行任何操作。

类型参数

TQueryFnData

TQueryFnData = unknown

TError

TError = Error

TData

TData = TQueryFnData

TQueryData

TQueryData = TQueryFnData

TQueryKey

TQueryKey extends readonly unknown[] = readonly unknown[]

TPageParam

TPageParam = never

参数

options

| QueryObserverOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey, TPageParam> | DefaultedQueryObserverOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>

调用方传入的查询选项。

返回值

DefaultedQueryObserverOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>

已默认化的选项，其中 queryHash 及其依赖的默认值（例如 refetchOnReconnect）均已填充。

继承自

TypeScript

1QueryCoreClient.defaultQueryOptions

ensureInfiniteQueryData()

TypeScript

1ensureInfiniteQueryData<TQueryFnData, TError = Error, TData = TQueryFnData, TQueryKey extends readonly unknown[] = readonly unknown[], TPageParam = unknown>(options: EnsureInfiniteQueryDataOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>): Promise<InfiniteData<TData, TPageParam>>;

定义位置：packages/query-core/src/queryClient.ts:813

返回无限查询的缓存数据；若尚无缓存，则执行拉取。启用 revalidateIfStale 后，过期的缓存数据也会在后台重新拉取。

类型参数

TQueryFnData

TQueryFnData

TError

TError = Error

TData

TData = TQueryFnData

TQueryKey

TQueryKey extends readonly unknown[] = readonly unknown[]

TPageParam

TPageParam = unknown

参数

options

EnsureInfiniteQueryDataOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>

无限查询选项。若该查询尚无缓存数据，则使用这些选项执行拉取。

返回值

Promise<InfiniteData<TData, TPageParam>>

一个 Promise，解析为缓存的 InfiniteData，或若尚无缓存则解析为拉取到的数据。

已弃用

请改用 queryClient.infiniteQuery({ ...options, staleTime: 'static' })。该方法将在下一个主版本中移除。

继承自

TypeScript

1QueryCoreClient.ensureInfiniteQueryData

ensureQueryData()

TypeScript

1ensureQueryData<TQueryFnData, TError = Error, TData = TQueryFnData, TQueryKey extends readonly unknown[] = readonly unknown[]>(options: EnsureQueryDataOptions<TQueryFnData, TError, TData, TQueryKey>): Promise<TData>;

定义位置：packages/query-core/src/queryClient.ts:208

返回查询的缓存数据；若尚无缓存，则执行拉取。启用 revalidateIfStale 后，过期的缓存数据也会在后台重新拉取。

类型参数

TQueryFnData

TQueryFnData

TError

TError = Error

TData

TData = TQueryFnData

TQueryKey

TQueryKey extends readonly unknown[] = readonly unknown[]

参数

options

EnsureQueryDataOptions<TQueryFnData, TError, TData, TQueryKey>

查询选项。若该查询尚无缓存数据，则使用这些选项执行拉取。

返回值

Promise<TData>

一个 Promise，解析为缓存的数据，或若尚无缓存则解析为拉取到的数据。

已弃用

请改用 queryClient.query({ ...options, staleTime: 'static' })。该方法将在下一个主版本中移除。

继承自

TypeScript

1QueryCoreClient.ensureQueryData

fetchInfiniteQuery()

TypeScript

1fetchInfiniteQuery<TQueryFnData, TError = Error, TData = TQueryFnData, TQueryKey extends readonly unknown[] = readonly unknown[], TPageParam = unknown>(options: FetchInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>): Promise<InfiniteData<TData, TPageParam>>;

定义位置：packages/query-core/src/queryClient.ts:757

拉取并缓存一个无限查询，或若其未过期则直接返回其缓存数据。

类型参数

TQueryFnData

TQueryFnData

TError

TError = Error

TData

TData = TQueryFnData

TQueryKey

TQueryKey extends readonly unknown[] = readonly unknown[]

TPageParam

TPageParam = unknown

参数

options

FetchInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>

无限查询选项，包括 queryKey、queryFn 和 initialPageParam。

返回值

Promise<InfiniteData<TData, TPageParam>>

一个 Promise，解析为缓存或拉取到的 InfiniteData，或因拉取错误而被拒绝。

已弃用

请改用 queryClient.infiniteQuery(options)。该方法将在下一个主版本中移除。

继承自

TypeScript

1QueryCoreClient.fetchInfiniteQuery

fetchQuery()

TypeScript

1fetchQuery<TQueryFnData, TError = Error, TData = TQueryFnData, TQueryKey extends readonly unknown[] = readonly unknown[], TPageParam = never>(options: FetchQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>): Promise<TData>;

定义位置：packages/query-core/src/queryClient.ts:651

拉取并缓存一个查询，或若其未过期则直接返回其缓存数据。与观察者不同，除非设置了 retry，否则该拉取不会重试。

类型参数

TQueryFnData

TQueryFnData

TError

TError = Error

TData

TData = TQueryFnData

TQueryKey

TQueryKey extends readonly unknown[] = readonly unknown[]

TPageParam

TPageParam = never

参数

options

FetchQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>

查询选项，包括 queryKey 和 queryFn（当查询需要拉取时使用）。

返回值

Promise<TData>

一个 Promise，解析为缓存或拉取到的数据，或因拉取错误而被拒绝。

已弃用

请改用 queryClient.query(options)。该方法将在下一个主版本中移除。

继承自

TypeScript

1QueryCoreClient.fetchQuery

getDefaultOptions()

TypeScript

1getDefaultOptions(): DefaultOptions;

定义位置：packages/query-core/src/queryClient.ts:897

返回创建客户端时或通过 QueryClient#setDefaultOptions 设置的默认选项。

返回值

DefaultOptions

客户端当前的默认选项。

示例

TypeScript

1import { QueryClient } from '@tanstack/query-core'2 3const queryClient = new QueryClient()4const defaultOptions = queryClient.getDefaultOptions()

继承自

TypeScript

1QueryCoreClient.getDefaultOptions

getMutationCache()

TypeScript

1getMutationCache(): MutationCache;

定义位置：packages/query-core/src/queryClient.ts:881

返回此客户端所连接的修改缓存。

返回值

MutationCache

MutationCache 实例。

示例

TypeScript

1import { QueryClient } from '@tanstack/query-core'2 3const queryClient = new QueryClient()4const mutationCache = queryClient.getMutationCache()5const mutations = mutationCache.findAll({ status: 'pending' })

继承自

TypeScript

1QueryCoreClient.getMutationCache

getMutationDefaults()

TypeScript

1getMutationDefaults(mutationKey: readonly unknown[]): OmitKeyof<MutationObserverOptions<any, any, any, any>, "mutationKey">;

定义位置：packages/query-core/src/queryClient.ts:1030

返回已注册的、其修改键部分匹配给定 mutationKey 的修改默认选项，这些选项通过 QueryClient#setMutationDefaults 注册。若多个已注册的默认选项匹配，则按注册顺序合并它们。

参数

mutationKey

readonly unknown[]

用于查找已注册默认选项的修改键。

返回值

OmitKeyof<MutationObserverOptions<any, any, any, any>, "mutationKey">

所有匹配注册项的合并后默认选项，若无匹配项则返回空对象。

示例

TypeScript

1const defaultOptions = queryClient.getMutationDefaults(['addPost'])

继承自

TypeScript

1QueryCoreClient.getMutationDefaults

getQueriesData()

TypeScript

1getQueriesData<TQueryFnData = unknown, TQueryFilters extends QueryFilters<any> = QueryFilters<readonly unknown[]>>(filters: TQueryFilters): [readonly unknown[], TQueryFnData | undefined][];

定义位置：packages/query-core/src/queryClient.ts:254

一种命令式（非响应式）方式，用于一次性获取多个查询的缓存数据。仅返回匹配给定筛选条件的查询；若无匹配项，则返回空数组。

由于匹配的查询可能持有不同结构的数据（例如宽泛的筛选条件可能匹配具有无关数据类型的查询），因此 TQueryFnData 泛型默认为 unknown 而非推断得出。传入更具体的类型是为那些明确知道所有匹配查询持有相同数据结构的调用点提供的便利——但该类型不会与实际缓存内容进行校验。

类型参数

TQueryFnData

TQueryFnData = unknown

TQueryFilters

TQueryFilters extends QueryFilters<any> = QueryFilters<readonly unknown[]>

参数

filters

TQueryFilters

用于筛选待读取查询的过滤器。

返回值

[readonly unknown[], TQueryFnData | undefined][]

一个查询键与数据对的数组。对于尚无缓存数据的查询，其数据为 undefined。

参见

QueryClient#getQueryData

示例

TypeScript

1const data = queryClient.getQueriesData({ queryKey: ['posts'] })

继承自

TypeScript

1QueryCoreClient.getQueriesData

getQueryCache()

TypeScript

1getQueryCache(): QueryCache;

定义位置：packages/query-core/src/queryClient.ts:865

返回此客户端所连接的查询缓存。

返回值

QueryCache

QueryCache 实例。

示例

TypeScript

1import { QueryClient } from '@tanstack/query-core'2 3const queryClient = new QueryClient()4const queryCache = queryClient.getQueryCache()5const queries = queryCache.findAll({ queryKey: ['posts'] })

继承自

TypeScript

1QueryCoreClient.getQueryCache

getQueryData()

TypeScript

1getQueryData<TQueryFnData = unknown, TTaggedQueryKey extends readonly unknown[] = readonly unknown[], TInferredQueryFnData = InferDataFromTag<TQueryFnData, TTaggedQueryKey>>(queryKey: TTaggedQueryKey): TInferredQueryFnData | undefined;

定义于：packages/query-core/src/queryClient.ts:188

以命令式（非响应式）方式获取指定查询键（QueryKey）对应的数据。
仅应在需要读取最新数据的回调或函数中使用，例如用于乐观更新。

提示：请勿在组件内部使用此函数，因为它不会接收到更新。
请使用 useQuery 创建一个 QueryObserver 来订阅变更。

类型参数

TQueryFnData

TQueryFnData = unknown

TTaggedQueryKey

TTaggedQueryKey extends readonly unknown[] = readonly unknown[]

TInferredQueryFnData

TInferredQueryFnData = InferDataFromTag<TQueryFnData, TTaggedQueryKey>

参数

queryKey

TTaggedQueryKey

待读取查询的查询键。

返回值

TInferredQueryFnData | undefined

该查询的缓存数据；若尚无任何查询使用此查询键，则返回 undefined。

参见

QueryClient#getQueriesData

继承自

TypeScript

1QueryCoreClient.getQueryData

getQueryDefaults()

TypeScript

1getQueryDefaults(queryKey: readonly unknown[]): OmitKeyof<QueryObserverOptions<any, any, any, any, any>, "queryKey">;

定义于：packages/query-core/src/queryClient.ts:970

返回已注册的、其查询键（query key）与给定 queryKey 部分匹配的查询默认选项，这些默认选项通过 QueryClient#setQueryDefaults 注册。若存在多个匹配的默认选项，则按注册顺序合并。

参数

queryKey

readonly unknown[]

用于查找已注册默认选项的查询键。

返回值

OmitKeyof<QueryObserverOptions<any, any, any, any, any>, "queryKey">

所有匹配注册项的合并后默认选项；若无匹配项，则返回空对象。

示例

TypeScript

1const defaultOptions = queryClient.getQueryDefaults(['posts'])

继承自

TypeScript

1QueryCoreClient.getQueryDefaults

getQueryState()

TypeScript

1getQueryState<TQueryFnData = unknown, TError = Error, TTaggedQueryKey extends readonly unknown[] = readonly unknown[], TInferredQueryFnData = InferDataFromTag<TQueryFnData, TTaggedQueryKey>, TInferredError = InferErrorFromTag<TError, TTaggedQueryKey>>(queryKey: TTaggedQueryKey): 2  | QueryState<TInferredQueryFnData, TInferredError>3  | undefined;

定义于：packages/query-core/src/queryClient.ts:371

以命令式（非响应式）方式获取已有查询的状态。若该查询不存在，则返回 undefined。

类型参数

TQueryFnData

TQueryFnData = unknown

TError

TError = Error

TTaggedQueryKey

TTaggedQueryKey extends readonly unknown[] = readonly unknown[]

TInferredQueryFnData

TInferredQueryFnData = InferDataFromTag<TQueryFnData, TTaggedQueryKey>

TInferredError

TInferredError = InferErrorFromTag<TError, TTaggedQueryKey>

参数

queryKey

TTaggedQueryKey

待读取查询的查询键。

返回值

| QueryState<TInferredQueryFnData, TInferredError> | undefined

该查询的状态；若不存在使用此查询键的查询，则返回 undefined。

示例

TypeScript

1const state = queryClient.getQueryState(['posts'])2console.log(state?.dataUpdatedAt)

继承自

TypeScript

1QueryCoreClient.getQueryState

infiniteQuery()

TypeScript

1infiniteQuery<TQueryFnData, TError = Error, TData = InfiniteData<TQueryFnData, unknown>, TQueryKey extends readonly unknown[] = readonly unknown[], TPageParam = unknown>(options: InfiniteQueryExecuteOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>): Promise<TData[] extends InfiniteData<TQueryFnData, unknown>[] ? InfiniteData<TQueryFnData, TPageParam> : TData>;

定义于：packages/query-core/src/queryClient.ts:726

异步方法，用于拉取并缓存无限查询（infinite query），成功时解析为 InfiniteData 对象，失败时抛出错误。

行为类似 QueryClient#query，接受相同选项（不包括 initialPageParam），但额外要求提供 initialPageParam，并可选提供 pages / getNextPageParam 对，用于从起始位置重新拉取固定数量的页。

此方法替代了已弃用的 fetchInfiniteQuery，并与 { staleTime: 'static' } 一起替代了已弃用的 ensureInfiniteQueryData。

类型参数

TQueryFnData

TQueryFnData

TError

TError = Error

TData

TData = InfiniteData<TQueryFnData, unknown>

TQueryKey

TQueryKey extends readonly unknown[] = readonly unknown[]

TPageParam

TPageParam = unknown

参数

options

InfiniteQueryExecuteOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>

无限查询选项，包括 queryKey、queryFn 和 initialPageParam。

返回值

Promise<TData[] extends InfiniteData<TQueryFnData, unknown>[] ? InfiniteData<TQueryFnData, TPageParam> : TData>

一个 Promise，成功时解析为 InfiniteData，或若提供了 select 则解析为其结果；失败时拒绝，错误来自拉取过程或 select。

示例

TypeScript

1try {2  const data = await queryClient.infiniteQuery({ queryKey, queryFn, initialPageParam: 0 })3  console.log(data.pages)4} catch (error) {5  console.log(error)6}

继承自

TypeScript

1QueryCoreClient.infiniteQuery

invalidateQueries()

TypeScript

1invalidateQueries<TTaggedQueryKey extends readonly unknown[] = readonly unknown[]>(filters?: InvalidateQueryFilters<TTaggedQueryKey>, options?: InvalidateOptions): Promise<void>;

定义于：packages/query-core/src/queryClient.ts:495

将匹配给定筛选器的查询标记为失效。与 QueryClient#removeQueries 不同，失效的查询仍保留在缓存中。

除非 filters.refetchType 为 'none'，否则匹配的查询将通过 QueryClient#refetchQueries 重新拉取，优先使用 filters.refetchType，其次使用 filters.type，最后使用 'active'。

类型参数

TTaggedQueryKey

TTaggedQueryKey extends readonly unknown[] = readonly unknown[]

参数

filters?

InvalidateQueryFilters<TTaggedQueryKey>

用于选择要使失效的查询的筛选器，以及 refetchType，用于控制后续重新拉取哪些查询。若未提供筛选器，则所有查询均被标记为失效。

options?

InvalidateOptions = {}

传入 QueryClient#refetchQueries，例如 cancelRefetch 和 throwOnError。

返回值

Promise<void>

一个 Promise，在重新拉取完成时解析；若 refetchType 为 'none'，则立即解析。

示例

TypeScript

1await queryClient.invalidateQueries({ queryKey: ['posts'], refetchType: 'active' })

继承自

TypeScript

1QueryCoreClient.invalidateQueries

isFetching()

TypeScript

1isFetching(filters?: Omit<QueryFilters<readonly unknown[]>, "fetchStatus">): number;

定义于：packages/query-core/src/queryClient.ts:151

返回缓存中当前正在拉取的查询数量，可选地按一组筛选器进行过滤。这包括后台拉取、加载新页以及加载更多无限查询结果。

参数

filters?

Omit<QueryFilters<readonly unknown[]>, "fetchStatus">

缩小需计数的拉取中查询的范围。若未提供筛选器，则统计所有拉取中的查询。

返回值

number

其 fetchStatus 为 'fetching' 的匹配查询的数量。

示例

TypeScript

1if (queryClient.isFetching()) {2  console.log('At least one query is fetching!')3}

继承自

TypeScript

1QueryCoreClient.isFetching

isMutating()

TypeScript

1isMutating<TMutationFilters extends MutationFilters<any, any, unknown, unknown> = MutationFilters<any, any, unknown, unknown>>(filters?: NoInfer<Omit<TMutationFilters, "status">>): number;

定义于：packages/query-core/src/queryClient.ts:169

返回缓存中当前处于等待中（pending）状态的修改（mutation）数量，可选地按一组筛选器进行过滤。

类型参数

TMutationFilters

TMutationFilters extends MutationFilters<any, any, unknown, unknown> = MutationFilters<any, any, unknown, unknown>

参数

filters?

NoInfer<Omit<TMutationFilters, "status">>

缩小需计数的等待中修改的范围。若未提供筛选器，则统计所有等待中的修改。

返回值

number

其 status 为 'pending' 的匹配修改的数量。

示例

TypeScript

1if (queryClient.isMutating()) {2  console.log('At least one mutation is pending!')3}

继承自

TypeScript

1QueryCoreClient.isMutating

mount()

TypeScript

1mount(): void;

定义于：packages/query-core/src/queryClient.ts:103

由框架适配器的 QueryClientProvider 等价物在挂载时调用，以开始监听焦点（focus）/在线（online）事件，并恢复已暂停的修改。通过内部挂载计数实现引用计数，因此共享同一 QueryClient 的嵌套或多个 Provider 在最后一个卸载前不会销毁共享监听器。

返回值

void

继承自

TypeScript

1QueryCoreClient.mount

prefetchInfiniteQuery()

TypeScript

1prefetchInfiniteQuery<TQueryFnData, TError = Error, TData = TQueryFnData, TQueryKey extends readonly unknown[] = readonly unknown[], TPageParam = unknown>(options: FetchInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>): Promise<void>;

定义于：packages/query-core/src/queryClient.ts:785

像 QueryClient#fetchInfiniteQuery 一样拉取并缓存无限查询，但忽略结果和任何错误。

类型参数

TQueryFnData

TQueryFnData

TError

TError = Error

TData

TData = TQueryFnData

TQueryKey

TQueryKey extends readonly unknown[] = readonly unknown[]

TPageParam

TPageParam = unknown

参数

options

FetchInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>

无限查询选项，包括 queryKey、queryFn 和 initialPageParam。

返回值

Promise<void>

一个 Promise，在拉取完成后解析。它永远不会拒绝。

已弃用

请改用 queryClient.infiniteQuery(options)。你可以使用 .catch(noop) 吞掉错误。此方法将在下一个主版本中移除。

继承自

TypeScript

1QueryCoreClient.prefetchInfiniteQuery

prefetchQuery()

TypeScript

1prefetchQuery<TQueryFnData = unknown, TError = Error, TData = TQueryFnData, TQueryKey extends readonly unknown[] = readonly unknown[]>(options: FetchQueryOptions<TQueryFnData, TError, TData, TQueryKey>): Promise<void>;

定义于：packages/query-core/src/queryClient.ts:690

像 QueryClient#fetchQuery 一样拉取并缓存查询，但忽略结果和任何错误。

类型参数

TQueryFnData

TQueryFnData = unknown

TError

TError = Error

TData

TData = TQueryFnData

TQueryKey

TQueryKey extends readonly unknown[] = readonly unknown[]

参数

options

FetchQueryOptions<TQueryFnData, TError, TData, TQueryKey>

查询选项，包括 queryKey 和 queryFn（当查询需要拉取时使用）。

返回值

Promise<void>

一个 Promise，在拉取完成后解析。它永远不会拒绝。

已弃用

请改用 queryClient.query(options)。你可以使用 .catch(noop) 吞掉错误。此方法将在下一个主版本中移除。

继承自

TypeScript

1QueryCoreClient.prefetchQuery

query()

TypeScript

1query<TQueryFnData, TError = Error, TData = TQueryFnData, TQueryData = TQueryFnData, TQueryKey extends readonly unknown[] = readonly unknown[], TPageParam = never>(options: QueryExecuteOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey, TPageParam>): Promise<TData>;

定义于：packages/query-core/src/queryClient.ts:599

异步方法，用于拉取并缓存查询，成功时解析为数据，失败时抛出错误。

若查询已在缓存中且其数据尚未过期（依据给定的 staleTime），则直接返回缓存数据，无需拉取。否则执行拉取，Promise 在拉取完成后解析。若提供了 select 函数，则无论数据来自缓存还是新拉取，都会在返回前应用该函数处理。

与响应式观察者不同，此处默认禁用重试（retry: false），除非显式配置；因为没有组件可捕获抛出的错误并通过重新渲染来重试。

可接受的选项是 QueryObserverOptions，但需排除仅对响应式观察者有意义的字段 —— enabled、refetchInterval、refetchIntervalInBackground、refetchOnWindowFocus、refetchOnReconnect、refetchOnMount、retryOnMount、notifyOnChangeProps、throwOnError、suspense 和 placeholderData 不属于该方法的选项。

该方法取代了已弃用的 fetchQuery；与 { staleTime: 'static' } 结合使用时，也取代了已弃用的 ensureQueryData。

类型参数

TQueryFnData

TQueryFnData

TError

TError = Error

TData

TData = TQueryFnData

TQueryData

TQueryData = TQueryFnData

TQueryKey

TQueryKey extends readonly unknown[] = readonly unknown[]

TPageParam

TPageParam = never

参数

options

QueryExecuteOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey, TPageParam>

查询选项，包括 queryKey 以及查询需要拉取时所用的 queryFn。

返回值

Promise<TData>

一个 Promise，其解析值为数据，或若提供了 select 则为其返回结果；若拉取失败或 select 抛出错误，则该 Promise 将以对应错误拒绝。

示例

TypeScript

1try {2  const data = await queryClient.query({ queryKey, queryFn, staleTime: 10000 })3} catch (error) {4  console.log(error)5}

继承自

TypeScript

1QueryCoreClient.query

refetchQueries()

TypeScript

1refetchQueries<TTaggedQueryKey extends readonly unknown[] = readonly unknown[]>(filters?: RefetchQueryFilters<TTaggedQueryKey>, options?: RefetchOptions): Promise<void>;

定义于：packages/query-core/src/queryClient.ts:540

无论查询是否过期，均按给定筛选条件重新拉取匹配的查询。若未提供筛选条件，则缓存中的所有查询都将被重新拉取。禁用的查询或静态查询（即其观察者仅具有静态 staleTime）永远不会被重新拉取。

默认情况下（cancelRefetch: true），当前正在运行的拉取操作会在新拉取开始前被取消。除非将 throwOnError 设为 true，否则返回的 Promise 不会因单个查询失败而拒绝。

初始即处于暂停状态的拉取操作不会延迟返回的 Promise；即使 throwOnError 为 true，其后续发生的错误仍会被处理。

类型参数

TTaggedQueryKey

TTaggedQueryKey extends readonly unknown[] = readonly unknown[]

参数

filters?

RefetchQueryFilters<TTaggedQueryKey>

用于选择要重新拉取哪些查询的筛选条件。若不提供筛选条件，则缓存中所有查询均被包含在内。

options?

RefetchOptions = {}

将 cancelRefetch 设为 false 可保留正在运行的拉取操作而不取消它；将 throwOnError 设为 true 可使 Promise 在最初未暂停的重新拉取失败时拒绝。

返回值

Promise<void>

一个 Promise，当所有最初未暂停的匹配重新拉取操作均已 settle 后即解析。

示例

TypeScript

1// refetch all active queries partially matching a query key:2await queryClient.refetchQueries({ queryKey: ['posts'], type: 'active' })

继承自

TypeScript

1QueryCoreClient.refetchQueries

removeQueries()

TypeScript

1removeQueries<TTaggedQueryKey extends readonly unknown[] = readonly unknown[]>(filters?: QueryFilters<TTaggedQueryKey>): void;

定义于：packages/query-core/src/queryClient.ts:398

移除缓存中匹配给定筛选条件的查询。与 QueryClient#invalidateQueries 或 QueryClient#refetchQueries 不同，此方法从缓存中移除匹配的查询，而非重新拉取它们。若不提供筛选条件，则缓存中的所有查询均被移除。

类型参数

TTaggedQueryKey

TTaggedQueryKey extends readonly unknown[] = readonly unknown[]

参数

filters?

QueryFilters<TTaggedQueryKey>

用于选择要移除哪些查询的筛选条件。若不提供筛选条件，则所有查询均被移除。

返回值

void

示例

TypeScript

1queryClient.removeQueries({ queryKey: ['posts'], exact: true })

继承自

TypeScript

1QueryCoreClient.removeQueries

resetQueries()

TypeScript

1resetQueries<TTaggedQueryKey extends readonly unknown[] = readonly unknown[]>(filters?: QueryFilters<TTaggedQueryKey>, options?: ResetOptions): Promise<void>;

定义于：packages/query-core/src/queryClient.ts:423

将匹配给定筛选条件的查询重置为其初始状态（例如任何 initialData），并通知订阅者，而非将其从缓存中移除。匹配集合中处于活跃状态的查询随后会被重新拉取，且返回的 Promise 将在该重新拉取操作 settle 后解析。

类型参数

TTaggedQueryKey

TTaggedQueryKey extends readonly unknown[] = readonly unknown[]

参数

filters?

QueryFilters<TTaggedQueryKey>

用于选择要重置哪些查询的筛选条件。若不提供筛选条件，则所有查询均被重置。

options?

ResetOptions

传递给匹配的活跃查询的重新拉取操作，例如 cancelRefetch 和 throwOnError。

返回值

Promise<void>

一个 Promise，当匹配的活跃查询的重新拉取操作 settle 后即解析。

示例

TypeScript

1await queryClient.resetQueries({ queryKey: ['posts'], exact: true })

继承自

TypeScript

1QueryCoreClient.resetQueries

resumePausedMutations()

TypeScript

1resumePausedMutations(): Promise<unknown>;

定义于：packages/query-core/src/queryClient.ts:846

恢复因网络连接中断而暂停的修改操作。若客户端当前处于离线状态，则此方法不执行任何操作（立即解析）。

返回值

Promise<unknown>

一个 Promise，当已恢复的修改操作全部 settle 后即解析。

示例

TypeScript

1import { QueryClient } from '@tanstack/query-core'2 3const queryClient = new QueryClient()4await queryClient.resumePausedMutations()

继承自

TypeScript

1QueryCoreClient.resumePausedMutations

setDefaultOptions()

TypeScript

1setDefaultOptions(options: DefaultOptions): void;

定义于：packages/query-core/src/queryClient.ts:918

动态设置该客户端的默认选项，覆盖此前已定义的任何默认选项。

参数

options

DefaultOptions

查询和修改操作的新默认选项。

返回值

void

参见

QueryClient#getDefaultOptions

示例

TypeScript

1import { QueryClient } from '@tanstack/query-core'2 3const queryClient = new QueryClient()4queryClient.setDefaultOptions({5  queries: {6    staleTime: Infinity,7  },8})

继承自

TypeScript

1QueryCoreClient.setDefaultOptions

setMutationDefaults()

TypeScript

1setMutationDefaults<TData = unknown, TError = Error, TVariables = void, TOnMutateResult = unknown>(mutationKey: readonly unknown[], options: OmitKeyof<MutationObserverOptions<TData, TError, TVariables, TOnMutateResult>, "mutationKey">): void;

定义于：packages/query-core/src/queryClient.ts:1000

为修改键部分匹配给定 mutationKey 的修改操作设置默认选项。与 QueryClient#setQueryDefaults 类似，当多个已注册的默认选项匹配同一修改键时，注册顺序会影响最终合并结果。

类型参数

TData

TData = unknown

TError

TError = Error

TVariables

TVariables = void

TOnMutateResult

TOnMutateResult = unknown

参数

mutationKey

readonly unknown[]

用于部分匹配修改键的修改键。

options

OmitKeyof<MutationObserverOptions<TData, TError, TVariables, TOnMutateResult>, "mutationKey">

应用于匹配修改操作的默认选项。

返回值

void

参见

QueryClient#getMutationDefaults

示例

TypeScript

1queryClient.setMutationDefaults(['addPost'], { mutationFn: addPost })

继承自

TypeScript

1QueryCoreClient.setMutationDefaults

setQueriesData()

TypeScript

1setQueriesData<TQueryFnData, TQueryFilters extends QueryFilters<any> = QueryFilters<readonly unknown[]>>(2   filters: TQueryFilters, 3   updater: Updater<NoInfer<TQueryFnData> | undefined, NoInfer<TQueryFnData> | undefined>, 4   options?: SetDataOptions5): [readonly unknown[], TQueryFnData | undefined][];

定义于：packages/query-core/src/queryClient.ts:339

一种同步方式，用于立即批量更新多个查询的缓存数据，支持通过筛选条件或查询键的部分匹配来定位目标查询。仅更新已存在且匹配给定筛选条件的查询；不会创建新的缓存条目。内部对每个匹配的查询调用 QueryClient#setQueryData。

类型参数

TQueryFnData

TQueryFnData

TQueryFilters

TQueryFilters extends QueryFilters<any> = QueryFilters<readonly unknown[]>

参数

filters

TQueryFilters

用于选择要更新哪些现有查询的筛选条件。

updater

Updater<NoInfer<TQueryFnData> | undefined, NoInfer<TQueryFnData> | undefined>

新数据本身，或一个接收每个匹配查询当前数据（可能为 undefined）并返回新数据的函数。

options?

SetDataOptions

设置 updatedAt 可覆盖写入数据所记录的时间戳。

返回值

[readonly unknown[], TQueryFnData | undefined][]

每个匹配查询对应一个 [queryKey, data] 元组，其结构及 undefined 情况与 QueryClient#setQueryData 完全一致。

示例

TypeScript

1queryClient.setQueriesData({ queryKey: ['posts'] }, (oldPosts) =>2  oldPosts ? oldPosts.filter((post) => post.id !== deletedId) : oldPosts,3)

继承自

TypeScript

1QueryCoreClient.setQueriesData

setQueryData()

TypeScript

1setQueryData<TQueryFnData = unknown, TTaggedQueryKey extends readonly unknown[] = readonly unknown[], TInferredQueryFnData = InferDataFromTag<TQueryFnData, TTaggedQueryKey>>(2   queryKey: TTaggedQueryKey, 3   updater: Updater<4  | InferDataFromTag<NoInfer<TQueryFnData>, TTaggedQueryKey>5  | undefined, NoInfer<TInferredQueryFnData> | undefined>, 6   options?: SetDataOptions7): NoInfer<TInferredQueryFnData> | undefined;

定义于：packages/query-core/src/queryClient.ts:286

一种同步方式，用于立即更新某个查询的缓存数据。若更新器（或传入的值）解析为 undefined，则缓存保持不变且不会创建新查询；否则，若该查询尚不存在，则会创建它。如需通过查询键的部分匹配一次性更新多个查询，请改用 QueryClient#setQueriesData。

更新操作必须以不可变方式进行：请勿就地修改 oldData，或通过 QueryClient#getQueryData 之前获取的数据。

类型参数

TQueryFnData

TQueryFnData = unknown

TTaggedQueryKey

TTaggedQueryKey extends readonly unknown[] = readonly unknown[]

TInferredQueryFnData

TInferredQueryFnData = InferDataFromTag<TQueryFnData, TTaggedQueryKey>

参数

queryKey

TTaggedQueryKey

要设置数据的查询键。

updater

Updater< | InferDataFromTag<NoInfer<TQueryFnData>, TTaggedQueryKey> | undefined, NoInfer<TInferredQueryFnData> | undefined>

新数据本身，或一个接收当前数据（可能为 undefined）并返回新数据的函数。

options?

SetDataOptions

设置 updatedAt 可覆盖写入数据所记录的时间戳。

返回值

NoInfer<TInferredQueryFnData> | undefined

实际写入的数据，或若更新器返回 undefined 则返回 undefined — 此时跳过写入操作，缓存保持不变。

示例

TypeScript

1queryClient.setQueryData(['posts'], newPosts)2 3// Or, using an updater function that receives the current data:4queryClient.setQueryData(['posts'], (oldPosts) => [...oldPosts, newPost])

继承自

TypeScript

1QueryCoreClient.setQueryData

setQueryDefaults()

TypeScript

1setQueryDefaults<TQueryFnData = unknown, TError = Error, TData = TQueryFnData, TQueryData = TQueryFnData>(queryKey: readonly unknown[], options: Partial<OmitKeyof<QueryObserverOptions<TQueryFnData, TError, TData, TQueryData>, "queryKey">>): void;

定义于：packages/query-core/src/queryClient.ts:938

为查询键部分匹配给定 queryKey 的查询设置默认选项。

若多个已注册的查询默认选项匹配某一查询键，则它们将按注册顺序由 QueryClient#getQueryDefaults 合并；因此，请按从最通用到最具体的顺序注册默认选项 — 更具体的默认选项应后注册，以便优先级更高。

类型参数

TQueryFnData

TQueryFnData = unknown

TError

TError = Error

TData

TData = TQueryFnData

TQueryData

TQueryData = TQueryFnData

参数

queryKey

readonly unknown[]

用于部分匹配查询键的查询键。

options

Partial<OmitKeyof<QueryObserverOptions<TQueryFnData, TError, TData, TQueryData>, "queryKey">>

应用于匹配查询的默认选项。

返回值

void

示例

TypeScript

1queryClient.setQueryDefaults(['posts'], { queryFn: fetchPosts })2 3await queryClient.query({ queryKey: ['posts'] })

继承自

TypeScript

1QueryCoreClient.setQueryDefaults

unmount()

TypeScript

1unmount(): void;

定义于：packages/query-core/src/queryClient.ts:126

unmount() 是 QueryClient#mount 的逆操作——由框架适配器在其 QueryClientProvider 等效逻辑卸载时调用。仅当挂载计数（mount count）回落至 0 时，才会拆除焦点（focus）和网络在线（online）监听器。

返回值

void

继承自

TypeScript

1QueryCoreClient.unmount