QueryClient

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

QueryClient 用于与查询和修改的缓存进行交互。它拥有一个 QueryCache 和一个 MutationCache（若未传入则创建默认实例），并持有应用于通过它创建的查询和修改的默认选项。

示例

1const queryClient = new QueryClient({2  defaultOptions: {3    queries: {4      staleTime: Infinity,5    },6  },7})8 9await queryClient.query({ queryKey: ['posts'], queryFn: fetchPosts })

构造函数

构造函数

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

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

参数

config?

QueryClientConfig = {}

返回值

QueryClient

方法

cancelQueries()

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，当所有取消操作均完成时即解析。

示例

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

clear()

1clear(): void;

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

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

返回值

void

示例

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

defaultMutationOptions()

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

已默认化的选项。

defaultQueryOptions()

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）均已填充。

ensureInfiniteQueryData()

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' })。该方法将在下一个主版本中移除。

ensureQueryData()

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' })。该方法将在下一个主版本中移除。

fetchInfiniteQuery()

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)。该方法将在下一个主版本中移除。

fetchQuery()

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)。该方法将在下一个主版本中移除。

getDefaultOptions()

1getDefaultOptions(): DefaultOptions;

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

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

返回值

DefaultOptions

客户端当前的默认选项。

示例

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

getMutationCache()

1getMutationCache(): MutationCache;

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

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

返回值

MutationCache

MutationCache 实例。

示例

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

getMutationDefaults()

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

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

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

参数

mutationKey

readonly unknown[]

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

返回值

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

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

示例

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

getQueriesData()

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

示例

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

getQueryCache()

1getQueryCache(): QueryCache;

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

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

返回值

QueryCache

QueryCache 实例。

示例

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

getQueryData()

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

getQueryDefaults()

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

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

返回已注册的默认选项，这些选项适用于其查询键部分匹配给定 queryKey 的查询，注册方式为 QueryClient#setQueryDefaults。若存在多个匹配的已注册默认项，则按注册顺序合并它们。

参数

queryKey

readonly unknown[]

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

返回值

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

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

示例

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

getQueryState()

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。

示例

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

infiniteQuery()

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

一种异步方法，用于拉取并缓存无限查询，成功时解析为 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 抛出的错误。

示例

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

invalidateQueries()

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'，则立即解析。

示例

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

isFetching()

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

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

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

参数

filters?

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

缩小被计数的拉取中查询的范围。若未提供过滤器，则所有拉取中的查询均被计数。

返回值

number

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

示例

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

isMutating()

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

返回缓存中当前处于等待状态的修改数量，可选地匹配一组过滤器。

类型参数

TMutationFilters

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

参数

filters?

NoInfer<Omit<TMutationFilters, "status">>

缩小被计数的等待中修改的范围。若未提供过滤器，则所有等待中的修改均被计数。

返回值

number

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

示例

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

mount()

1mount(): void;

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

由框架适配器的 QueryClientProvider 等效方法在挂载时调用，以开始监听焦点/在线事件并恢复已暂停的修改。内部通过挂载计数进行引用计数，因此共享同一 QueryClient 的嵌套或多个提供者，仅在最后一个提供者卸载时才会销毁共享监听器。

返回值

void

prefetchInfiniteQuery()

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) 吞掉错误。此方法将在下一个主版本中移除。

prefetchQuery()

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) 吞掉错误。此方法将在下一个主版本中移除。

query()

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 抛出的错误。

示例

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

refetchQueries()

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

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

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

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

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

类型参数

TTaggedQueryKey

TTaggedQueryKey extends readonly unknown[] = readonly unknown[]

参数

filters?

RefetchQueryFilters<TTaggedQueryKey>

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

options?

RefetchOptions = {}

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

返回值

Promise<void>

一个 Promise，当所有未初始暂停的匹配查询完成重新拉取后即解析。

示例

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

removeQueries()

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

示例

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

resetQueries()

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

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

将匹配给定筛选器的查询重置为其初始状态（例如任何 initialData），并通知订阅者，而非移除它们。匹配集合中的活跃查询随后会被重新拉取，且返回的 Promise 在该重新拉取完成后即解析。

类型参数

TTaggedQueryKey

TTaggedQueryKey extends readonly unknown[] = readonly unknown[]

参数

filters?

QueryFilters<TTaggedQueryKey>

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

options?

ResetOptions

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

返回值

Promise<void>

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

示例

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

resumePausedMutations()

1resumePausedMutations(): Promise<unknown>;

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

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

返回值

Promise<unknown>

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

示例

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

setDefaultOptions()

1setDefaultOptions(options: DefaultOptions): void;

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

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

参数

options

DefaultOptions

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

返回值

void

参见

QueryClient#getDefaultOptions

示例

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

setMutationDefaults()

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

示例

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

setQueriesData()

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 相同。

示例

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

setQueryData()

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 — 此时跳过写入操作，缓存保持不变。

示例

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

setQueryDefaults()

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

示例

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

unmount()

1unmount(): void;

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

QueryClient#mount 的逆向操作 — 由框架适配器的 QueryClientProvider 等价物在卸载时调用。仅当挂载计数回到 0 时，才拆除焦点/在线监听器。

返回值

void