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 的嵌套或多个 Provider，仅在最后一个卸载时才会销毁共享监听器。

返回值

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