QueryClient

QueryClient 可用于与缓存交互：

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 })

其可用方法有：

• 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 为所有查询和变更定义默认值。
  • 您还可以定义用于水合的默认值

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

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

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 以仅在数据早于特定时间量时才获取：

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>

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

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>>

prefetchQuery 是一个异步方法，可用于在需要或使用 useQuery 及其相关项渲染之前预取查询。该方法的工作方式与 fetchQuery 相同，只是它不会抛出或返回任何数据。

await queryClient.prefetchQuery({ queryKey, queryFn })

await queryClient.prefetchQuery({ queryKey, queryFn })

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

await queryClient.prefetchQuery({ queryKey })

await queryClient.prefetchQuery({ queryKey })

选项

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

返回值

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

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

await queryClient.prefetchInfiniteQuery({ queryKey, queryFn })

await queryClient.prefetchInfiniteQuery({ queryKey, queryFn })

选项

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

返回值

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

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

const data = queryClient.getQueryData(queryKey)

const data = queryClient.getQueryData(queryKey)

选项

• queryKey: QueryKey：查询键

返回值

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

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

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

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

选项

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

返回值

• Promise<TData>

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

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>>

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

const data = queryClient.getQueriesData(filters)

const data = queryClient.getQueriesData(filters)

选项

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

返回值

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

警告

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

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

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

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

queryClient.setQueryData(queryKey, updater)

queryClient.setQueryData(queryKey, updater)

选项

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

使用更新程序值

setQueryData(queryKey, newData)

setQueryData(queryKey, newData)

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

使用更新程序函数

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

setQueryData(queryKey, (oldData) => newData)

setQueryData(queryKey, (oldData) => newData)

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

不可变性

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

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

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

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

选项

• queryKey: QueryKey：查询键

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

queryClient.setQueriesData(filters, updater)

queryClient.setQueriesData(filters, updater)

选项

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

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

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

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 时，如果已有请求正在运行，则不会进行重新获取。

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,
})

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

返回值

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

注意

• 由于只有禁用的观察者而“禁用”的查询永远不会被重新获取。
• 由于只有具有静态 StaleTime 的观察者而“静态”的查询永远不会被重新获取。

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

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

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

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

选项

• filters?: QueryFilters：查询过滤器

返回值

此方法不返回任何内容

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

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

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

选项

• filters?: QueryFilters：查询过滤器

返回值

此方法不返回任何内容

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

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

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

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

选项

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

返回值

此方法返回一个 Promise，该 Promise 在所有活动查询都已重新获取后解析。

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

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

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

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

选项

• filters?: QueryFilters：查询过滤器

返回值

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

此 isMutating 方法返回一个 integer，表示缓存中当前正在获取的变更数量（如果有）。

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

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

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

选项

• filters: MutationFilters：变更过滤器

返回值

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

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

const defaultOptions = queryClient.getDefaultOptions()

const defaultOptions = queryClient.getDefaultOptions()

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

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

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

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

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

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

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

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

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 合并，因此应按以下顺序进行注册：从最通用的键到最不通用的键。 这样，更具体的默认值将覆盖更通用的默认值。

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

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

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

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

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 类似，此处的注册顺序很重要。

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

const queryCache = queryClient.getQueryCache()

const queryCache = queryClient.getQueryCache()

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

const mutationCache = queryClient.getMutationCache()

const mutationCache = queryClient.getMutationCache()

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

queryClient.clear()

queryClient.clear()

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

queryClient.resumePausedMutations()

queryClient.resumePausedMutations()