TanStackQuery v5
自动
框架
版本
菜单
开始入门
指南 & 概念
API 参考
ESLint
社区资源
示例
插件

QueryClient

QueryClient

QueryClient 可用于与缓存进行交互

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

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

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

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

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

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

其可用方法有

选项

  • queryCache?: QueryCache
    • 可选
    • 此客户端连接到的查询缓存。
  • mutationCache?: MutationCache
    • 可选
    • 此客户端连接到的突变缓存。
  • defaultOptions?: DefaultOptions
    • 可选
    • 为此 queryClient 的所有查询和突变定义默认值。
    • 您还可以定义用于 水合 的默认值

queryClient.fetchQuery

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

如果查询存在且数据未失效或早于给定的 staleTime，则将返回缓存中的数据。否则，它将尝试获取最新数据。

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

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

指定 staleTime 以仅在数据早于特定时间量时才获取

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

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，但可用于获取和缓存无限查询。

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

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 相同，只是它不会抛出或返回任何数据。

tsx
await queryClient.prefetchQuery({ queryKey, queryFn })

await queryClient.prefetchQuery({ queryKey, queryFn })

您甚至可以在配置中将其与默认 queryFn 一起使用！

tsx
await queryClient.prefetchQuery({ queryKey })

await queryClient.prefetchQuery({ queryKey })

选项

prefetchQuery 的选项与 fetchQuery 的选项完全相同。

返回

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

queryClient.prefetchInfiniteQuery

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

tsx
await queryClient.prefetchInfiniteQuery({ queryKey, queryFn })

await queryClient.prefetchInfiniteQuery({ queryKey, queryFn })

选项

prefetchInfiniteQuery 的选项与 fetchQuery 的选项完全相同。

返回

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

queryClient.getQueryData

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

tsx
const data = queryClient.getQueryData(queryKey)

const data = queryClient.getQueryData(queryKey)

选项

返回

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

queryClient.ensureQueryData

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

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

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

选项

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

返回

  • Promise<TData>

queryClient.ensureInfiniteQueryData

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

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

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

选项

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

返回

  • Promise<InfiniteData<TData, TPageParam>>

queryClient.getQueriesData

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

tsx
const data = queryClient.getQueriesData(filters)

const data = queryClient.getQueriesData(filters)

选项

  • filters: QueryFilters: 查询过滤器
    • 如果传递了过滤器，将返回具有与过滤器匹配的 queryKeys 的数据

返回

  • [queryKey: QueryKey, data: TQueryFnData | undefined][]
    • 匹配的查询键的元组数组，如果没有匹配项，则为 []。元组是查询键及其关联数据。

注意事项

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

这种区别更像是为知道将返回哪种结构的 ts 开发人员提供的“便利”。

queryClient.setQueryData

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

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

tsx
queryClient.setQueryData(queryKey, updater)

queryClient.setQueryData(queryKey, updater)

选项

  • queryKey: QueryKey: 查询键
  • updater: TQueryFnData | undefined | ((oldData: TQueryFnData | undefined) => TQueryFnData | undefined)
    • 如果传递了非函数，则数据将更新为此值
    • 如果传递了函数，它将接收旧数据值，并有望返回一个新值。

使用更新器值

tsx
setQueryData(queryKey, newData)

setQueryData(queryKey, newData)

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

使用更新器函数

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

tsx
setQueryData(queryKey, (oldData) => newData)

setQueryData(queryKey, (oldData) => newData)

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

不可变性

通过 setQueryData 进行的更新必须以不可变的方式执行。请勿尝试通过就地改变 oldData 或通过 getQueryData 检索的数据来直接写入缓存。

queryClient.getQueryState

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

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

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

选项

queryClient.setQueriesData

setQueriesData 是一个同步函数，可用于通过使用过滤器函数或部分匹配查询键来立即更新多个查询的缓存数据。只会更新与传递的 queryKey 或 queryFilter 匹配的查询 - 不会创建新的缓存条目。在幕后，将为每个现有查询调用 setQueryData。

tsx
queryClient.setQueriesData(filters, updater)

queryClient.setQueriesData(filters, updater)

选项

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

queryClient.invalidateQueries

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

  • 如果您不希望活动查询重新获取，而只是标记为无效，则可以使用 refetchType: 'none' 选项。
  • 如果您还希望非活动查询重新获取，请使用 refetchType: 'all' 选项
tsx
await queryClient.invalidateQueries(
  {
    queryKey: ['posts'],
    exact,
    refetchType: 'active',
  },
  { throwOnError, cancelRefetch },
)

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

选项

  • filters?: QueryFilters: 查询过滤器
    • queryKey?: QueryKey: 查询键
    • refetchType?: 'active' | 'inactive' | 'all' | 'none'
      • 默认为 'active'
      • 当设置为 active 时，只有与重新获取谓词匹配并通过 useQuery 及其友元积极呈现的查询才会在后台重新获取。
      • 当设置为 inactive 时，只有与重新获取谓词匹配且未通过 useQuery 及其友元积极呈现的查询才会在后台重新获取。
      • 当设置为 all 时，所有与重新获取谓词匹配的查询都将在后台重新获取。
      • 当设置为 none 时，不会重新获取任何查询，并且与重新获取谓词匹配的查询将仅标记为无效。
  • options?: InvalidateOptions:
    • throwOnError?: boolean
      • 当设置为 true 时，如果任何查询重新获取任务失败，此方法将抛出错误。
    • cancelRefetch?: boolean
      • 默认为 true
        • 默认情况下，在发出新请求之前，将取消当前正在运行的请求
      • 当设置为 false 时，如果已经有请求正在运行，则不会进行重新获取。

queryClient.refetchQueries

refetchQueries 方法可用于根据特定条件重新获取查询。

示例

tsx
// refetch all queries:
await queryClient.refetchQueries()

// refetch all stale queries:
await queryClient.refetchQueries({ stale: true })

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

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

// refetch all queries:
await queryClient.refetchQueries()

// refetch all stale queries:
await queryClient.refetchQueries({ stale: true })

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

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

选项

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

返回

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

queryClient.cancelQueries

cancelQueries 方法可用于根据查询键或查询的任何其他功能可访问的属性/状态来取消传出的查询。

当执行乐观更新时，这最有用，因为您可能需要取消任何传出的查询重新获取，以便它们在解析时不会破坏您的乐观更新。

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

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

选项

返回

此方法不返回任何内容

queryClient.removeQueries

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

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

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

选项

返回

此方法不返回任何内容

queryClient.resetQueries

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

这将通知订阅者 - 与 clear 不同，后者删除所有订阅者 - 并将查询重置为其预加载状态 - 与 invalidateQueries 不同。如果查询具有 initialData，则查询的数据将重置为该数据。如果查询处于活动状态，它将被重新获取。

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

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

选项

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

返回

此方法返回一个 promise，当所有活动查询都已重新获取时，该 promise 将解析。

queryClient.isFetching

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

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

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

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

选项

返回

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

queryClient.isMutating

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

tsx
if (queryClient.isMutating()) {
  console.log('At least one mutation is fetching!')
}

if (queryClient.isMutating()) {
  console.log('At least one mutation is fetching!')
}

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

选项

返回

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

queryClient.getDefaultOptions

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

tsx
const defaultOptions = queryClient.getDefaultOptions()

const defaultOptions = queryClient.getDefaultOptions()

queryClient.setDefaultOptions

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

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

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

queryClient.getQueryDefaults

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

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

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

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

queryClient.setQueryDefaults

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

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

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

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

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

选项

  • queryKey: QueryKey: 查询键
  • options: QueryOptions

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

queryClient.getMutationDefaults

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

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

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

queryClient.setMutationDefaults

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

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

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

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

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

选项

  • mutationKey: unknown[]
  • options: MutationOptions

与 setQueryDefaults 类似，注册顺序在此处也很重要。

queryClient.getQueryCache

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

tsx
const queryCache = queryClient.getQueryCache()

const queryCache = queryClient.getQueryCache()

queryClient.getMutationCache

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

tsx
const mutationCache = queryClient.getMutationCache()

const mutationCache = queryClient.getMutationCache()

queryClient.clear

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

tsx
queryClient.clear()

queryClient.clear()

queryClient.resumePausedMutations

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

tsx
queryClient.resumePausedMutations()

queryClient.resumePausedMutations()
在 GitHub 上编辑
迁移到 v5
QueryCache
想要跳过文档吗？
Query.gg - The Official React Query Course - TanStack
“如果您真的想*真正*理解 React Query，那么没有比 query.gg 更好的方法了”—Tanner Linsley