QueryClient

`QueryClient`

QueryClient 可用于与缓存进行交互：

import { QueryClient } from '@tanstack/react-query'

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: Infinity,
    },
  },
})

await queryClient.prefetchQuery({ queryKey: ['posts'], queryFn: fetchPosts })

它包含以下方法：

queryClient.fetchQuery
queryClient.fetchInfiniteQuery
queryClient.prefetchQuery
queryClient.prefetchInfiniteQuery
queryClient.getQueryData
queryClient.ensureQueryData
queryClient.ensureInfiniteQueryData
queryClient.getQueriesData
queryClient.setQueryData
queryClient.getQueryState
queryClient.setQueriesData
queryClient.invalidateQueries
queryClient.refetchQueries
queryClient.cancelQueries
queryClient.removeQueries
queryClient.resetQueries
queryClient.isFetching
queryClient.isMutating
queryClient.getDefaultOptions
queryClient.setDefaultOptions
queryClient.getQueryDefaults
queryClient.setQueryDefaults
queryClient.getMutationDefaults
queryClient.setMutationDefaults
queryClient.getQueryCache
queryClient.getMutationCache
queryClient.clear
queryClient.resumePausedMutations

选项

queryCache?: QueryCache
- 可选
- 该客户端连接的查询缓存。
mutationCache?: MutationCache
- 可选
- 该客户端连接的突变缓存。
defaultOptions?: DefaultOptions
- 可选
- 为此 queryClient 定义所有查询和突变的默认值。
- 您也可以为水合（hydration）定义默认值。

`queryClient.fetchQuery`

fetchQuery 是一个异步方法，可用于获取并缓存一个查询。它将解析为数据或抛出错误。如果您只想获取查询结果而不需要返回值，请使用 prefetchQuery 方法。

如果查询已存在且数据未被标记为无效或未超过给定的 staleTime，则将返回缓存中的数据。否则，它将尝试获取最新数据。

try {
  const data = await queryClient.fetchQuery({ queryKey, queryFn })
} catch (error) {
  console.log(error)
}

指定 staleTime 以仅在数据超过一定时间后才重新获取：

try {
  const data = await queryClient.fetchQuery({
    queryKey,
    queryFn,
    staleTime: 10000,
  })
} catch (error) {
  console.log(error)
}

选项

fetchQuery 的选项与 useQuery 完全相同，除了以下这些：enabled, refetchInterval, refetchIntervalInBackground, refetchOnWindowFocus, refetchOnReconnect, refetchOnMount, notifyOnChangeProps, throwOnError, select, suspense, placeholderData；这些选项仅适用于 useQuery 和 useInfiniteQuery。您可以通过查看源码获取更清晰的说明。

返回值

Promise<TData>

`queryClient.fetchInfiniteQuery`

fetchInfiniteQuery 与 fetchQuery 类似，但可用于获取和缓存无限查询。

try {
  const data = await queryClient.fetchInfiniteQuery({ queryKey, queryFn })
  console.log(data.pages)
} catch (error) {
  console.log(error)
}

选项

fetchInfiniteQuery 的选项与 fetchQuery 完全相同。

返回值

Promise<InfiniteData<TData, TPageParam>>

`queryClient.prefetchQuery`

prefetchQuery 是一个异步方法，可用于在使用 useQuery 及其相关方法之前预先获取查询。该方法的工作方式与 fetchQuery 相同，但不会抛出错误或返回任何数据。

await queryClient.prefetchQuery({ queryKey, queryFn })

您甚至可以在配置中使用默认的 queryFn！

await queryClient.prefetchQuery({ queryKey })

选项

prefetchQuery 的选项与 fetchQuery 完全相同。

返回值

Promise<void>
- 返回一个 Promise，如果不需要获取则立即解析，否则在查询执行后解析。它不会返回任何数据或抛出任何错误。

`queryClient.prefetchInfiniteQuery`

prefetchInfiniteQuery 与 prefetchQuery 类似，但可用于预取并缓存无限查询。

await queryClient.prefetchInfiniteQuery({ queryKey, queryFn })

选项

prefetchInfiniteQuery 的选项与 fetchQuery 完全相同。

返回值

Promise<void>
- 返回一个 Promise，如果不需要获取则立即解析，否则在查询执行后解析。它不会返回任何数据或抛出任何错误。

`queryClient.getQueryData`

getQueryData 是一个同步函数，可用于获取现有查询的缓存数据。如果查询不存在，则返回 undefined。

const data = queryClient.getQueryData(queryKey)

选项

queryKey: QueryKey: 查询键（Query Keys）

返回值

data: TQueryFnData | undefined
- 缓存查询的数据，如果查询不存在则为 undefined。

`queryClient.ensureQueryData`

ensureQueryData 是一个异步函数，可用于获取现有查询的缓存数据。如果查询不存在，则调用 queryClient.fetchQuery 并返回其结果。

const data = await queryClient.ensureQueryData({ queryKey, queryFn })

选项

与 fetchQuery 相同的选项
revalidateIfStale: boolean
- 可选
- 默认为 false
- 如果设置为 true，陈旧数据将在后台重新获取，但会立即返回缓存数据。

返回值

Promise<TData>

`queryClient.ensureInfiniteQueryData`

ensureInfiniteQueryData 是一个异步函数，可用于获取现有无限查询的缓存数据。如果查询不存在，则调用 queryClient.fetchInfiniteQuery 并返回其结果。

const data = await queryClient.ensureInfiniteQueryData({
  queryKey,
  queryFn,
  initialPageParam,
  getNextPageParam,
})

选项

与 fetchInfiniteQuery 相同的选项
revalidateIfStale: boolean
- 可选
- 默认为 false
- 如果设置为 true，陈旧数据将在后台重新获取，但会立即返回缓存数据。

返回值

Promise<InfiniteData<TData, TPageParam>>

`queryClient.getQueriesData`

getQueriesData 是一个同步函数，可用于获取多个查询的缓存数据。只有与传入的 queryKey 或 queryFilter 匹配的查询才会被返回。如果没有匹配的查询，则返回空数组。

const data = queryClient.getQueriesData(filters)

选项

filters: QueryFilters: 查询过滤器（Query Filters）
- 如果传递了过滤器，则返回与过滤器匹配的查询键的数据。

返回值

[queryKey: QueryKey, data: TQueryFnData | undefined][]
- 匹配的查询键及其关联数据的元组数组，如果没有匹配项则返回 []。元组包含查询键和其对应的数据。

注意事项

由于返回数据中的每个元组结构可能各不相同（例如，使用过滤器返回“活跃”查询可能会返回不同类型的数据），TData 泛型默认为 unknown。如果您为 TData 提供更具体的类型，则假设您确定每个元组的数据条目都是相同类型。

这种区分更多是为了解决 TypeScript 开发者知道将返回何种结构的“便利性”。

`queryClient.setQueryData`

setQueryData 是一个同步函数，可用于立即更新查询的缓存数据。如果查询不存在，则会创建它。如果查询在默认的 gcTime（5 分钟）内未被查询钩子使用，该查询将被垃圾回收。要同时更新多个查询并部分匹配查询键，您需要使用 queryClient.setQueriesData。

使用 setQueryData 和 fetchQuery 的区别在于，setQueryData 是同步的，并假设您已经同步地拥有数据。如果您需要异步获取数据，建议您重新获取查询键或使用 fetchQuery 来处理异步获取。

queryClient.setQueryData(queryKey, updater)

选项

queryKey: QueryKey: 查询键（Query Keys）
updater: TQueryFnData | undefined | ((oldData: TQueryFnData | undefined) => TQueryFnData | undefined)
- 如果传递非函数值，则数据将更新为此值
- 如果传递函数，则它将接收旧数据值并应返回新值。

使用更新值

setQueryData(queryKey, newData)

如果值为 undefined，则查询数据不会更新。

使用更新函数

为了方便语法，您还可以传递一个更新函数，该函数接收当前数据值并返回新值：

setQueryData(queryKey, (oldData) => newData)

如果更新函数返回 undefined，则查询数据不会更新。如果更新函数接收到 undefined 作为输入，您可以返回 undefined 以中止更新，从而不创建新的缓存条目。

不可变性

通过 setQueryData 的更新必须以 不可变 的方式进行。不要尝试通过直接修改 oldData 或通过 getQueryData 获取的数据来直接写入缓存。

`queryClient.getQueryState`

getQueryState 是一个同步函数，可用于获取现有查询的状态。如果查询不存在，则返回 undefined。

const state = queryClient.getQueryState(queryKey)
console.log(state.dataUpdatedAt)

选项

queryKey: QueryKey: 查询键（Query Keys）

`queryClient.setQueriesData`

setQueriesData 是一个同步函数，可用于立即更新多个查询的缓存数据，通过使用过滤函数或部分匹配查询键。只有与传入的 queryKey 或 queryFilter 匹配的查询才会被更新——不会创建新的缓存条目。在底层，setQueryData 会对每个现有查询调用。

queryClient.setQueriesData(filters, updater)

选项

filters: QueryFilters: 查询过滤器（Query Filters）
- 如果传递了过滤器，则匹配过滤器的 queryKeys 将被更新
updater: TQueryFnData | (oldData: TQueryFnData | undefined) => TQueryFnData
- setQueryData 的更新函数或新数据，将为每个匹配的 queryKey 调用

`queryClient.invalidateQueries`

invalidateQueries 方法可用于使缓存中的单个或多个查询失效并重新获取，基于它们的查询键或查询的任何其他可访问属性/状态。默认情况下，所有匹配的查询会立即被标记为无效，并且活跃的查询会在后台重新获取。

如果您 不希望活跃查询重新获取，而只是希望它们被标记为无效，可以使用 refetchType: 'none' 选项。
如果您 希望非活跃查询也重新获取，请使用 refetchType: 'all' 选项
对于重新获取，queryClient.refetchQueries 会被调用。

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

选项

filters?: QueryFilters: 查询过滤器（Query Filters）
- queryKey?: QueryKey: 查询键（Query Keys）
- refetchType?: 'active' | 'inactive' | 'all' | 'none'
  - 默认为 'active'
  - 当设置为 active 时，只有匹配重新获取谓词且通过 useQuery 及其相关方法正在渲染的活跃查询会在后台重新获取。
  - 当设置为 inactive 时，只有匹配重新获取谓词且未通过 useQuery 及其相关方法渲染的非活跃查询会在后台重新获取。
  - 当设置为 all 时，所有匹配重新获取谓词的查询都会在后台重新获取。
  - 当设置为 none 时，不会重新获取任何查询，那些匹配谓词的查询将仅被标记为无效。
options?: InvalidateOptions:
- throwOnError?: boolean
  - 当设置为 true 时，如果任何查询重新获取任务失败，此方法将抛出错误。
- cancelRefetch?: boolean
  - 默认为 true
    默认情况下，当前正在运行的请求将在新请求发出前被取消
  - 当设置为 false 时，如果已有请求正在运行，则不会进行重新获取。

`queryClient.refetchQueries`

refetchQueries 方法可用于基于某些条件重新获取查询。

示例：

// 重新获取所有查询：
await queryClient.refetchQueries()

// 重新获取所有陈旧的查询：
await queryClient.refetchQueries({ stale: true })

// 重新获取所有部分匹配查询键的活跃查询：
await queryClient.refetchQueries({ queryKey: ['posts'], type: 'active' })

// 重新获取所有精确匹配查询键的活跃查询：
await queryClient.refetchQueries({
  queryKey: ['posts', 1],
  type: 'active',
  exact: true,
})

选项

filters?: QueryFilters: 查询过滤器（Query Filters）
options?: RefetchOptions:
- throwOnError?: boolean
  - 当设置为 true 时，如果任何查询重新获取任务失败，此方法将抛出错误。
- cancelRefetch?: boolean
  - 默认为 true
    默认情况下，当前正在运行的请求将在新请求发出前被取消
  - 当设置为 false 时，如果已有请求正在运行，则不会进行重新获取。

返回值

此函数返回一个 Promise，当所有查询完成重新获取时解析。默认情况下，即使这些查询的重新获取失败，它也不会抛出错误，但可以通过将 throwOnError 选项设置为 true 来配置。

注意事项

“禁用”的查询（因为它们只有禁用的观察者）永远不会被重新获取。
“静态”的查询（因为它们只有具有静态 staleTime 的观察者）永远不会被重新获取。

`queryClient.cancelQueries`

cancelQueries 方法可用于基于查询键或查询的任何其他可访问属性/状态取消正在进行的查询。

这在执行乐观更新时最为有用，因为您可能需要取消任何正在进行的查询重新获取，以免它们在解析时覆盖您的乐观更新。

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

选项

filters?: QueryFilters: 查询过滤器（Query Filters）
cancelOptions?: CancelOptions: 取消选项（Cancel Options）

返回值

此方法不返回任何内容。

`queryClient.removeQueries`

removeQueries 方法可用于基于查询键或查询的任何其他可访问属性/状态从缓存中移除查询。

queryClient.removeQueries({ queryKey, exact: true })

选项

filters?: QueryFilters: 查询过滤器（Query Filters）

返回值

此方法不返回任何内容。

`queryClient.resetQueries`

resetQueries 方法可用于将缓存中的查询重置为其初始状态，基于查询键或查询的任何其他可访问属性/状态。

这将通知订阅者——与 clear 不同，clear 会移除所有订阅者——并将查询重置为其加载前的状态——与 invalidateQueries 不同。如果查询有 initialData，查询的数据将被重置为该值。如果查询是活跃的，它将被重新获取。

queryClient.resetQueries({ queryKey, exact: true })

选项

filters?: QueryFilters: 查询过滤器（Query Filters）
options?: ResetOptions:
- throwOnError?: boolean
  - 当设置为 true 时，如果任何查询重新获取任务失败，此方法将抛出错误。
- cancelRefetch?: boolean
  - 默认为 true
    默认情况下，当前正在运行的请求将在新请求发出前被取消
  - 当设置为 false 时，如果已有请求正在运行，则不会进行重新获取。

返回值

此方法返回一个 Promise，当所有活跃查询重新获取完成后解析。

`queryClient.isFetching`

此 isFetching 方法返回一个 整数，表示缓存中有多少查询正在获取（包括后台获取、加载新页面或加载更多无限查询结果）。

if (queryClient.isFetching()) {
  console.log('至少有一个查询正在获取！')
}

TanStack Query 还导出了一个方便的 useIsFetching 钩子，允许您在组件中订阅此状态，而无需手动订阅查询缓存。

选项

filters?: QueryFilters: 查询过滤器（Query Filters）

返回值

此方法返回正在获取的查询数量。

`queryClient.isMutating`

此 isMutating 方法返回一个 整数，表示缓存中有多少突变正在获取。

if (queryClient.isMutating()) {
  console.log('至少有一个突变正在获取！')
}

TanStack Query 还导出了一个方便的 useIsMutating 钩子，允许您在组件中订阅此状态，而无需手动订阅突变缓存。

选项

filters: MutationFilters: 突变过滤器（Mutation Filters）

返回值

此方法返回正在获取的突变数量。

`queryClient.getDefaultOptions`

getDefaultOptions 方法返回在创建客户端或使用 setDefaultOptions 时设置的默认选项。

const defaultOptions = queryClient.getDefaultOptions()

`queryClient.setDefaultOptions`

setDefaultOptions 方法可用于动态设置此 queryClient 的默认选项。先前定义的默认选项将被覆盖。

queryClient.setDefaultOptions({
  queries: {
    staleTime: Infinity,
  },
})

`queryClient.getQueryDefaults`

getQueryDefaults 方法返回为特定查询设置的默认选项：

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

请注意，如果多个查询默认值匹配给定的查询键，它们将根据注册顺序合并。参见 setQueryDefaults。

`queryClient.setQueryDefaults`

setQueryDefaults 可用于为特定查询设置默认选项：

queryClient.setQueryDefaults(['posts'], { queryFn: fetchPosts })

function Component() {
  const { data } = useQuery({ queryKey: ['posts'] })
}

选项

queryKey: QueryKey: 查询键（Query Keys）
options: QueryOptions

如 getQueryDefaults 所述，注册顺序很重要。由于 getQueryDefaults 会合并匹配的默认值，因此注册顺序应从 最通用的键 到 最不通用的键。这样，更具体的默认值将覆盖更通用的默认值。

`queryClient.getMutationDefaults`

getMutationDefaults 方法返回为特定突变设置的默认选项：

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

`queryClient.setMutationDefaults`

setMutationDefaults 可用于为特定突变设置默认选项：

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

function Component() {
  const { data } = useMutation({ mutationKey: ['addPost'] })
}

选项

mutationKey: unknown[]
options: MutationOptions

与 setQueryDefaults 类似，这里的注册顺序也很重要。

`queryClient.getQueryCache`

getQueryCache 方法返回此客户端连接的查询缓存。

const queryCache = queryClient.getQueryCache()

`queryClient.getMutationCache`

getMutationCache 方法返回此客户端连接的突变缓存。

const mutationCache = queryClient.getMutationCache()

`queryClient.clear`

clear 方法清除所有连接的缓存。

queryClient.clear()

`queryClient.resumePausedMutations`

可用于恢复因无网络连接而暂停的突变。

queryClient.resumePausedMutations()

上一页修改导致的失效 Invalidation From Mutations 下一页QueryCache

最后更新于16天前

这有帮助吗？