QueryClient

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

Its available methods are (它可用的方法有)

• 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
  • Optional (可选)
  • 此客户端连接到的查询缓存。
• mutationCache?: MutationCache
  • Optional (可选)
  • 此客户端连接到的突变缓存。
• defaultOptions?: DefaultOptions
  • Optional (可选)
  • 使用此 queryClient 定义所有查询和突变的默认值。
  • 您还可以定义用于 hydration 的默认值

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。您可以查看 源代码 以获得更清晰的了解。

Returns (返回)

• 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 完全相同。

Returns (返回)

• 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 完全相同。

Returns (返回)

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

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

await queryClient.prefetchInfiniteQuery({ queryKey, queryFn })

await queryClient.prefetchInfiniteQuery({ queryKey, queryFn })

选项

prefetchInfiniteQuery 的选项与 fetchQuery 完全相同。

Returns (返回)

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

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

const data = queryClient.getQueryData(queryKey)

const data = queryClient.getQueryData(queryKey)

选项

• queryKey: QueryKey: 查询键

Returns (返回)

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

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

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

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

选项

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

Returns (返回)

• 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
  • Optional (可选)
  • 默认为 false
  • 如果设置为 true，则将在后台重新获取陈旧数据，但会立即返回缓存的数据。

Returns (返回)

• Promise<InfiniteData<TData, TPageParam>>

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

const data = queryClient.getQueriesData(filters)

const data = queryClient.getQueriesData(filters)

选项

• filters: QueryFilters: 查询过滤器
  • 如果传入过滤器，将返回与过滤器匹配的 queryKeys 的数据。

Returns (返回)

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

注意事项

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

这种区分对于了解将返回哪种结构的 ts 开发人员来说更是一种“便利”。

setQueryData 是一个同步函数，可用于立即更新查询的缓存数据。如果查询不存在，它将被创建。如果查询在默认的 gcTime（5 分钟）内未被任何查询钩子使用，则该查询将被垃圾回收。要一次更新多个查询并部分匹配查询键，您需要改用 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: 查询过滤器
  • 如果传入过滤器，将更新与过滤器匹配的 queryKeys。
• 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 方法可用于根据某些条件重新获取查询。

示例

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

Returns (返回)

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

注释

• 由于仅拥有已禁用观察器的查询被“禁用”，因此它们将永远不会被重新获取。
• 由于仅拥有静态 staleTime 观察器的查询被认为是“静态”的，因此它们将永远不会被重新获取。

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

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

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

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

选项

• filters?: QueryFilters: 查询过滤器
• cancelOptions?: CancelOptions: 取消选项

Returns (返回)

此方法不返回任何内容。

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

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

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

选项

• filters?: QueryFilters: 查询过滤器

Returns (返回)

此方法不返回任何内容。

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

Returns (返回)

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

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

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 钩子，它允许您在组件中订阅此状态，而无需手动订阅查询缓存。

选项

• filters?: QueryFilters: 查询过滤器

Returns (返回)

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

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

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 钩子，它允许您在组件中订阅此状态，而无需手动订阅突变缓存。

选项

• filters: MutationFilters: 突变过滤器

Returns (返回)

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

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