TanStack Query异步状态管理--中文版（持续更新中）

JayYuen
VIP.5 如鱼得水
2,727 阅读32分钟

React Query API翻译参考

该文原版，如有翻译不妥之处，还请指点，谢谢！

useQuery

const {
  data,
  dataUpdatedAt,
  error,
  errorUpdatedAt,
  failureCount,
  failureReason,
  isError,
  isFetched,
  isFetchedAfterMount,
  isFetching,
  isPaused,
  isLoading,
  isLoadingError,
  isPlaceholderData,
  isPreviousData,
  isRefetchError,
  isRefetching,
  isInitialLoading,
  isStale,
  isSuccess,
  refetch,
  remove,
  status,
  fetchStatus,
} = useQuery({
  queryKey,
  queryFn,
  cacheTime,
  enabled,
  networkMode,
  initialData,
  initialDataUpdatedAt,
  keepPreviousData,
  meta,
  notifyOnChangeProps,
  onError,
  onSettled,
  onSuccess,
  placeholderData,
  queryKeyHashFn,
  refetchInterval,
  refetchIntervalInBackground,
  refetchOnMount,
  refetchOnReconnect,
  refetchOnWindowFocus,
  retry,
  retryOnMount,
  retryDelay,
  select,
  staleTime,
  structuralSharing,
  suspense,
  useErrorBoundary,
})

// 或者使用对象语法

const result = useQuery({
  queryKey,
  queryFn,
  enabled,
})

Options

  • queryKey: unknown[]

    • 必填
    • 用于此查询的查询键
    • 查询键将被哈希成稳定的哈希值。有关详细信息，请参阅查询键
    • 当此键更改时，查询将自动更新（只要 enabled 未设置为 false）

  • queryFn: (conent: QueryFunctionConent) => Promise<TData>

    • 必填，但只有在未定义默认查询函数时才需要。 有关更多信息，请参见 默认查询函数
    • 查询将用于请求数据的函数
    • 接收一个QueryFunctionContext
    • 必须返回一个 Promise，该 Promise 将解析数据或抛出错误。数据不能为 undefined

  • enabled: boolean

    • 将其设置为 false 以禁用自动运行此查询
    • 可用于依赖查询

  • networkMode: 'online' | 'always' | 'offlineFirst

    • 可选项
    • 默认为 'online'
    • 有关详细信息，请参阅网络模式

  • retry: boolean | number | (failureCount: number, error: TError) => boolean

    • 设置为 false，默认情况下不会重试失败的查询
    • 设置为 true，默认情况下会无限重试失败的查询
    • 设置为一个 number，例如 3，则失败的查询将一直重试，直到失败的查询次数达到该数字

  • retryOnMount: boolean

    • 设置为 false，如果查询包含错误，则在挂载时不会重试该查询。默认值为 true

  • retryDelay: number | (retryAttempt: number, error: TError) => number

    • 此函数接 retryAttempt 次数和实际 error，并返回下一次重试之前要应用的延迟时间（以毫秒为单位）
    • 像 attempt => Math.min(attempt > 1 ? 2 ** attempt * 1000 : 1000, 30 * 1000) 这样的函数应用指数回退
    • 像 attempt => attempt * 1000 这样的函数应用线性回退

  • staleTime: number | Infinity

    • 可选项
    • 默认值为 0
    • 数据被视为过期的时间(以毫秒为单位)。该值仅适用于定义它的钩子
    • 如果设置为 Infinity，则数据将永远不会被视为过期

  • cacheTime: number | Infinity

    • 默认值为 5 * 60 * 1000（5 分钟） 或在 SSR 期间为 Infinity
    • 未使用/不活动的缓存数据在内存中保留的时间（以毫秒为单位）。当查询的缓存变得未使用或不活动时，该缓存数据将在此持续时间后被垃圾回收。当指定不同的缓存时间时，将使用最长的缓存时间
    • 将其设置为 Infinity，则将禁用垃圾回收

  • queryKeyHashFn: (queryKey: QueryKey) => string

    • 可选项
    • 如果指定，则使用此函数将 queryKey 哈希为字符串

  • refetchInterval: number | false | ((data: TData | undefined, query: Query) => number | false)

    • 可选项
    • 设置为一个数字，则所有查询将以这个毫秒为单位的频率连续重新获取
    • 设置为一个函数，则该函数将使用最新的数据和查询来计算一个频率

  • refetchIntervalInBackground: boolean

    • 可选项
    • 设置为 true，则设置为连续使用 refetchInterval 重新获取的查询将在其选项卡/窗口处于后台时继续重新获取

  • refetchOnMount: boolean | "always" | ((query: Query) => boolean | "always")

    • 可选项
    • 默认为 true
    • 设置为 true，则在挂载时如果数据过期，查询将重新获取
    • 设置为 false，则查询将不会在挂载时重新获取
    • 设置为 "always"，则查询将始终在挂载时重新获取
    • 设置为函数，则该函数将使用查询来计算值

  • refetchOnWindowFocus: boolean | "always" | ((query: Query) => boolean | "always")

    • 可选项
    • 默认为 true
    • 设置为 true，则在窗口聚焦时如果数据过期，查询将重新获取
    • 设置为 false，则查询将不会在窗口聚焦时重新获取
    • 设置为 "always"，则查询将始终在窗口聚焦时重新获取
    • 设置为函数，则该函数将使用查询来计算值

  • refetchOnReconnect: boolean | "always" | ((query: Query) => boolean | "always")

    • 可选项
    • 默认为 true
    • 设置为 true，则在重新连接时如果数据过期，查询将重新获取
    • 设置为 false，则查询将不会在重新连接时重新获取
    • 设置为 "always"，则查询将始终在重新连接时重新获取
    • 设置为一个函数，则该函数将使用查询来计算值

  • notifyOnChangeProps: string[] | "all"

    • 可选项
    • 如果设置，则只有列出的任何属性发生更改时，组件才会重新渲染
    • 例如，如果设置为 ['data', 'error']，则组件只会在 data 或 error 属性更改时，组件才会重新渲染
    • 如果设置为 "all"，则组件将选择退出智能跟踪，并在每次查询更新时重新渲染
    • 默认情况下，将跟踪属性的访问，并且只有跟踪的属性之一发生更改时，组件才会重新渲染

  • onSuccess: (data: TData) => void

    • 可选项
    • 该函数将在查询成功获取新数据时触发

  • onError: (error: TError) => void

    • 可选项
    • 如果查询遇到错误，将触发该函数，并将错误作为参数传递

  • onSettled: (data?: TData, error?: TError) => void

    • 可选项
    • 该函数将在查询成功获取数据或发生错误时触发，并将数据或错误作为参数传递

  • select: (data: TData) => unknown

    • 可选项
    • 此选项可用于转换或选择查询函数返回的数据的一部分。它影响返回的数据值，但不影响存储在查询缓存中的内容

  • suspense: boolean

    • 可选项
    • 将此设置 true 为启用 suspense 模式
    • 当为 true 时，useQuery 在 status === 'loading' 时将暂停
    • 当为 true，useQuery 在 status === 'error' 时将会抛出运行时错误

  • initialData: TData | () => TData

    • 可选项
    • 如果设置，它将用作查询缓存的初始数据（只要查询尚未创建或缓存）
    • 如果设置为函数，该函数将在共享/根查询初始化期间调用一次，并且应该同步返回初始数据
    • 默认情况下，初始数据被视为过期，除非设置了 staleTime
    • initialData被持久化 到缓存中

  • initialDataUpdatedAt: number | (() => number | undefined)

    • 可选项
    • 如果设置，它将用作 initialData 本身最后更新的时间（以毫秒为单位）

  • placeholderData: TData | () => TData

    • 可选项
    • 如果设置，它将用作此特定查询观察器的占位符数据，同时查询仍在loading数据并且未提供初始数据
    • placeholderData不会持久化到缓存中

  • keepPreviousData: boolean

    • 可选项
    • 默认为false
    • 如果设置了此选项，当查询键发生变化时，将保留先前的数据以在获取新数据时使用

  • isDataEqual: (oldData: TData | undefined, newData: TData) => boolean

    • 已废弃。您可以通过将一个函数传递给 structuralSharing 来实现相同的功能：
      • structuralSharing: (oldData, newData) => isDataEqual(oldData, newData) ? oldData : replaceEqualDeep(oldData, newData)
    • 可选项
    • 此函数应该返回一个布尔值，指示是使用以前的数据（true）还是新的数据（false）作为查询的已解析数据

  • structuralSharing: boolean | ((oldData: TData | undefined, newData: TData) => TData)

    • 可选项
    • 默认为 true
    • 如果设置为 false，则查询结果之间的结构共享将被禁用
    • 如果设置为函数，则旧数据和新数据值将通过该函数传递，该函数应该将它们组合成查询的解析数据。通过这种方式，即使该数据包含不可序列化的值，也可以保留对旧数据的引用，以提高性能

  • useErrorBoundary: undefined | boolean | (error: TError, query: Query) => boolean

    • 默认为全局查询配置的 useErrorBoundary 值，该值为 undefined
    • 如果要在渲染阶段抛出错误并传播到最近的错误边界，请将其设置为 true
    • 如果要禁用 suspense 的默认行为，在错误边界中抛出错误，请将其设置为 false
    • 如果设置为函数，它将传递错误和查询，并应返回一个布尔值，指示是否在错误边界中显示错误（true）或将错误返回为状态（false）

  • meta: Record<string, unknown>

    • 可选项
    • 如果设置了该选项，将会在查询缓存条目上存储额外的信息，这些信息可以根据需要使用。它将在查询可用的任何地方访问，也是提供给 queryFn 的 QueryFunctionContext 的一部分

  • context?: React.Context<QueryClient | undefined>

    • 使用此选项来使用自定义的 React Query 上下文。否则将使用默认上下文 defaultContext

Returns

  • status: String

    • 将：

      • 当没有缓存数据并且尚未完成查询尝试时，状态为 loading
      • 当查询尝试导致错误时，状态为 error。查询对应的 error 属性包含从尝试的获取中接收到的错误
      • 当查询已经接收到响应并且没有错误准备好显示其数据时，状态为 success。查询对应的 data 属性是从成功获取中收到的数据，或者如果查询的 enabled 属性设置为 false 并且尚未获取数据，则 data 是查询在初始化时提供的第一个 initialData

  • isLoading: boolean

    • 这是从上面的 status 变量派生出来的布尔值，为方便起见提供

  • isSuccess: boolean

    • 这是从上面的 status 变量派生出来的布尔值，为方便起见提供

  • isError: boolean

    • 这是从上面的 status 变量派生出来的布尔值，为方便起见提供

  • isLoadingError: boolean

    • 如果在第一次获取数据时查询失败，该属性值将为 true

  • isRefetchError: boolean

    • 如果重新获取数据时查询失败，则该值为 true

  • data: TData

    • 默认为undefined
    • 上次成功解析查询的数据

  • dataUpdatedAt: number

    • 查询最近一次返回status为"success"的时间戳

  • error: null | TError

    • 默认为null
    • 查询的错误对象（如果引发错误）

  • errorUpdatedAt: number

    • 查询最近一次返回status为"error"的时间戳

  • isStale: boolean

    • 如果缓存中的数据无效或者数据比给定的staleTime早，则为true

  • isPlaceholderData: boolean

    • 如果显示的数据是占位符数据，则为true

  • isPreviousData: boolean

    • 如果设置了keepPreviousData并返回上一个查询中的数据时，则为true

  • isFetched: boolean

    • 如果查询已被提取，将是true

  • isFetchedAfterMount: boolean

    • 如果在组件安装后已获取查询，将是true
    • 此属性可用于不显示任何以前缓存的数据

  • fetchStatus: FetchStatus

    • fetching：当queryFn执行时为true，包括初始loading和后台重新获取
    • paused：查询想要获取，但已经paused
    • idle：查询未获取
    • 有关详细信息，请参阅网络模式。

  • isFetching: boolean

    • 为方便起见，从上述fetchStatus变量派生的布尔值

  • isPaused: boolean

    • 为方便起见，从上述fetchStatus变量派生的布尔值

  • isRefetching: boolean

    • 每当后台重新获取正在进行时则为true，不包括初始loading
    • 是否与isFetching && !isLoading相同

  • failureCount: number

    • 查询的失败次数
    • 每次查询失败时递增
    • 查询成功时重置为0

  • errorUpdateCount: number

    • 所有错误的总和

  • refetch: (options: { throwOnError: boolean, cancelRefetch: boolean }) => Promise<UseQueryResult>

    • 手动重新获取查询的函数
    • 如果查询错误，则只会记录错误。如果要抛出错误，请传递throwOnError: true选项
    • cancelRefetch?: boolean
      • 默认为true
        • 默认情况下，当前正在运行的请求将在发出新请求之前被取消
      • 设置为false时，如果已经有请求在运行，则不会重新获取

  • remove: () => void

    • 从缓存中删除查询的函数

useQueries

该useQueries钩子可用于获取不同数量的查询：

const results = useQueries({
  queries: [
    { queryKey: ['post', 1], queryFn: fetchPost, staleTime: Infinity},
    { queryKey: ['post', 2], queryFn: fetchPost, staleTime: Infinity}
  ]
})

Options

  • useQueries钩子接受一个带有查询键的选项对象，其值是一个数组，其中查询选项对象与useQuery钩子相同（不包括context选项）。

    • context?: React.Context<QueryClient | undefined>

      • 使用它可以使用自定义的 React Query 上下文。否则，将使用defaultContext

Returns

  • useQueries钩子返回一个包含所有查询结果的数组

useInfiniteQuery

const {
  fetchNextPage,
  fetchPreviousPage,
  hasNextPage,
  hasPreviousPage,
  isFetchingNextPage,
  isFetchingPreviousPage,
  ...result
} = useInfiniteQuery(queryKey, ({ pageParam = 1 }) => fetchPage(pageParam), {
  ...options,
  getNextPageParam: (lastPage, allPages) => lastPage.nextCursor,
  getPreviousPageParam: (firstPage, allPages) => firstPage.prevCursor,
})

Options

useInfiniteQuery的选项与useQuery钩子相同，并增加了以下内容：

  • queryFn: (context: QueryFunctionContext) => Promise<TData>

    • 必需，但仅当未定义默认查询函数defaultQueryFn时才需要
    • 查询将用于请求数据的函数
    • 接收一个QueryFunctionContext
    • 必须返回一个将解析数据或抛出错误的承诺
    • 如果需要在下面的道具中使用，请确保您返回数据和pageParam

  • getNextPageParam: (lastPage, allPages) => unknown | undefined

    • 当收到此查询的新数据时，此函数将接收无限数据列表的最后一页和所有页的完整数组
    • 它应该返回一个变量，该变量将作为最后一个可选参数传递给查询函数
    • 返回undefined以指示没有可用的下一页

  • getPreviousPageParam: (firstPage, allPages) => unknown | undefined

    • 当收到此查询的新数据时，此函数将接收无限数据列表的第一页和所有页的完整数组
    • 它应该返回一个变量，该变量将作为最后一个可选参数传递给查询函数
    • 返回undefined表示没有可用的上一页

Returns

useInfiniteQuery返回的属性与useQuery钩子相同，并增加了以下内容：

  • data.pages: TData[]

    • 包含所有页面的数组

  • data.pageParams: unknown[]

    • 包含所有页面参数的数组

  • isFetchingNextPage: boolean

    • 使用fetchNextPage获取下一页时将为true

  • isFetchingPreviousPage: boolean

    • 使用fetchPreviousPage获取上一页时将为true

  • fetchNextPage: (options?: FetchNextPageOptions) => Promise<UseInfiniteQueryResult>

    • 此函数允许您获取下一个“页面”的结果
    • options.pageParam: unknown 允许您手动指定页面参数，而不是使用getNextPageParam
    • options.cancelRefetch: boolean 如果设置为true，重复调用fetchNextPage将每次调用fetchPage，无论之前的调用是否已解析。此外，先前调用的结果将被忽略。如果设置为false，重复调用fetchNextPage 在第一次调用解决之前不会有任何效果。默认为true

  • fetchPreviousPage: (options?: FetchPreviousPageOptions) => Promise<UseInfiniteQueryResult>

    • 此功能允许您获取上一个“页面”的结果
    • options.pageParam: unknown 允许您手动指定页面参数，而不是使用getPreviousPageParam
    • options.cancelRefetch: boolean 与fetchNextPage相同

  • hasNextPage: boolean

    • 如果有下一页要获取（通过getNextPageParam选项知道）则是true

  • hasPreviousPage: boolean

    • 如果有上一页要获取（通过getPreviousPageParam选项知道）则是true

useMutation

const {
  data,
  error,
  isError,
  isIdle,
  isLoading,
  isPaused,
  isSuccess,
  mutate,
  mutateAsync,
  reset,
  status,
} = useMutation(mutationFn, {
  cacheTime,
  mutationKey,
  networkMode,
  onError,
  onMutate,
  onSettled,
  onSuccess,
  retry,
  retryDelay,
  useErrorBoundary,
  meta
})


mutate(variables, {
  onError,
  onSettled,
  onSuccess,
})

Options

  • mutationFn: (variables: TVariables) => Promise<TData>

    • 必需的
    • 执行异步任务并返回承诺的函数
    • variables是一个mutate传递给mutationFn的对象

  • cacheTime: number | Infinity

    • 未使用/非活动缓存数据保留在内存中的时间（以毫秒为单位）。当突变的缓存变得未使用或不活动时，该缓存数据将在此持续时间后被垃圾回收。当指定不同的缓存时间时，将使用最长的缓存时间
    • 如果设置为Infinity，将禁用垃圾回收

  • mutationKey: string

    • 可选的
    • 突变键可以设置为继承queryClient.setMutationDefaults的默认设置或用于识别 devtools 中的突变

  • networkMode: 'online' | 'always' | 'offlineFirst

    • 可选的
    • 默认为'online'
    • 有关详细信息，请参阅网络模式

  • onMutate: (variables: TVariables) => Promise<TContext | void> | TContext | void

    • 可选的
    • 此函数将在突变函数被触发之前触发，并传递与突变函数接收到的相同的变量
    • 在希望突变成功时对资源执行乐观更新
    • 如果发生突变失败，从此函数返回的值将传递给onError和onSettled函数，并且可用于回滚乐观更新

  • onSuccess: (data: TData, variables: TVariables, context?: TContext) => Promise<unknown> | void

    • 可选的
    • 此函数将在突变成功时触发，并将传递突变的结果
    • 如果一个承诺被返回，它将被等待并在继续之前解决

  • onError: (err: TError, variables: TVariables, context?: TContext) => Promise<unknown> | void

    • 可选的
    • 如果突变遇到错误，此函数将触发并将错误传递
    • 如果一个承诺被返回，它将被等待并在继续之前解决

  • onSettled: (data: TData, error: TError, variables: TVariables, context?: TContext) => Promise<unknown> | void

    • 可选的
    • 当突变成功获取或遇到错误并传递数据或错误时，此函数将触发
    • 如果一个承诺被返回，它将被等待并在继续之前解决

  • retry: boolean | number | (failureCount: number, error: TError) => boolean

    • 默认为0
    • 如果false，失败的突变将不会重试
    • 如果true，失败的突变将无限重试
    • 如果设置为number，例如3，失败的突变将重试，直到失败的突变计数达到该数字

  • retryDelay: number | (retryAttempt: number, error: TError) => number

    • 此函数接收一个retryAttempt整数和实际的error，并返回在下一次尝试之前应用的延迟（以毫秒为单位）
    • 像这样的函数attempt => Math.min(attempt > 1 ? 2 ** attempt * 1000 : 1000, 30 * 1000)应用指数退避
    • 像这样的函数attempt => attempt * 1000应用线性退避

  • useErrorBoundary: undefined | boolean | (error: TError) => boolean

    • 默认为全局查询配置的useErrorBoundary值，即undefined
    • 如果您希望在渲染阶段抛出突变错误并传播到最近的错误边界，请将其设置为true
    • 将此设置false为禁用将错误抛出到错误边界的行为
    • 如果设置为函数，它将被传递错误并返回一个布尔值，指示是在错误边界（true）中显示错误还是将错误作为状态返回（false）

  • meta: Record<string, unknown>

    • 可选的
    • 如果设置，则存储突变缓存条目上的额外信息，以供需要时使用。只要mutation可用，就可以访问它（例如MutationCache的onError,onSuccess功能）

  • context?: React.Context<QueryClient | undefined>

    • 使用它来使用自定义的 React Query 上下文。否则，将使用defaultContext

Returns

  • mutate: (variables: TVariables, { onSuccess, onSettled, onError }) => void

    • 您可以使用变量调用突变函数以触发突变，并可选择覆盖传递给useMutation

    • variables: TVariables

      • 可选的
      • 传递给mutationFn的variables对象

    • 其余的选项扩展了上述useMutation钩子中描述的相同选项

    • 如果您发出多个请求，onSuccess只会在您最近一次调用之后触发

  • mutateAsync: (variables: TVariables, { onSuccess, onSettled, onError }) => Promise<TData>

    • 类似于mutate，但返回一个可以等待的承诺

  • status: string

    • 将会：

      • idle 突变函数执行前的初始状态
      • loading 如果突变当前正在执行
      • error 如果最后一次突变尝试导致错误
      • success 如果最后一次突变尝试成功

  • isIdle, isLoading, isSuccess, isError: 来自status的布尔变量

  • isPaused: boolean

    • 如果突变已经paused则为true
    • 有关详细信息，请参阅网络模式

  • data: undefined | unknown

    • 默认为undefined
    • 上次成功解析查询的数据

  • error: null | TError

    • 查询的错误对象（如果遇到错误）

  • reset: () => void

    • 清除突变内部状态的函数（即，它将突变重置为其初始状态）

useIsFetching

useIsFetching是一个可选的钩子，它返回您的应用程序在后台加载或获取查询的number（对于应用程序范围的加载指示器很有用）。

import { useIsFetching } from '@tanstack/react-query'
// How many queries are fetching?
const isFetching = useIsFetching()
// How many queries matching the posts prefix are fetching?
const isFetchingPosts = useIsFetching(['posts'])

Options

  • queryKey?: QueryKey:查询键

  • filters?: QueryFilters:查询过滤器

  • context?: React.Context<QueryClient | undefined>

    • 使用它来使用自定义的 React Query 上下文。否则，将使用defaultContext

Returns

  • isFetching: number

    • 将是您的应用程序当前在后台加载或获取的查询的number

useIsMutating

useIsMutating是一个可选的钩子，它返回您的应用程序正在获取突变的number（对于应用程序范围的加载指示器很有用）。

import { useIsMutating } from '@tanstack/react-query'
// How many mutations are fetching?
const isMutating = useIsMutating()
// How many mutations matching the posts prefix are fetching?
const isMutatingPosts = useIsMutating(['posts'])

Options

  • mutationKey?: string | unknown[]

  • filters?: MutationFilters:变异过滤器

  • context?: React.Context<QueryClient | undefined>

    • 使用它来使用自定义的 React Query 上下文。否则，将使用defaultContext

Returns

  • isMutating: number

    • 将是您的应用程序当前正在获取突变的number

QueryClient

QueryClient可用于与缓存交互：

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


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


await queryClient.prefetchQuery(['posts'], fetchPosts)

其可用的方法有：

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

Options

  • queryCache?: QueryCache

    • 可选的
    • 此客户端连接到的查询缓存

  • mutationCache?: MutationCache

    • 可选的
    • 此客户端连接到的突变缓存

  • logger?: Logger

    • 可选的
    • 此客户端用于记录调试信息、警告和错误的日志记录器。如果未设置，console则为默认记录器

  • defaultOptions?: DefaultOptions

    • 可选的
    • 使用此 queryClient 为所有查询和突变定义默认值

queryClient.fetchQuery

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

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

使用fetchQuery和setQueryData之间的区别在于，fetchQuery是异步的，并将确保在获取数据时，不会使用相同查询的useQuery实例创建重复的查询请求。

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

Options

fetchQuery的选项与useQuery的选项完全相同，除了以下内容：enabled, refetchInterval, refetchIntervalInBackground, refetchOnWindowFocus, refetchOnReconnect, notifyOnChangeProps, onSuccess, onError, onSettled, useErrorBoundary, select, suspense, keepPreviousData, placeholderData; 严格适用于 useQuery 和 useInfiniteQuery。您可以查看源代码以获得更清晰的信息。

Returns

  • Promise<TData>

queryClient.fetchInfiniteQuery

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

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

Options

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

Returns

  • Promise<InfiniteData<TData>>

queryClient.prefetchQuery

prefetchQuery是一种异步方法，可用于在需要查询或与useQuery好友一起呈现之前预取查询。该方法的工作原理与fetchQuery相同，只是它不会抛出或返回任何数据。

await queryClient.prefetchQuery(queryKey, queryFn)

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

await queryClient.prefetchQuery(queryKey)

Options

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

Returns

  • Promise<void>

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

queryClient.prefetchInfiniteQuery

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

await queryClient.prefetchInfiniteQuery(queryKey, queryFn)

Options

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

Returns

  • Promise<void>

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

queryClient.getQueryData

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

const data = queryClient.getQueryData(queryKey)

Options

Returns

  • data: TData | undefined

    • 缓存查询的数据，如果查询不存在,则为undefined

queryClient.getQueriesData

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

const data = queryClient.getQueriesData(queryKey | filters)

Options

  • queryKey: QueryKey：查询键 | filters: QueryFilters：查询过滤器

    • 如果 queryKey 作为参数传递，则返回与 queryKeys 模糊匹配的数据
    • 如果传递了一个过滤器，将返回与过滤器匹配的 queryKeys 数据

Returns

  • [queryKey:QueryKey, data:TData | unknown][]

    • 匹配查询键的元组数组，如果没有匹配项，则为[]。元组是查询键及其关联数据

注意事项

因为每个元组中返回的数据可以是不同的结构（例如：使用过滤器返回“active”查询可以返回不同的数据类型），TData泛型默认为unknown。如果您为TData提供更具体的类型，则假定您确定每个元组的数据条目都是相同的类型。 这种区别对于ts开发者来说更“方便”，因为他们知道将返回哪个结构。

queryClient.setQueryData

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

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

queryClient.setQueryData(queryKey, updater)

Options

  • queryKey: QueryKey：查询键

  • updater: TData | (oldData: TData | undefined) => TData | undefined

    • 如果传入的是非函数，数据会更新到此值
    • 如果传递了一个函数，它将接收旧数据值并希望返回一个新数据值

使用更新器值

setQueryData(queryKey, newData)

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

使用更新器函数

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

setQueryData(queryKey, oldData => newData)

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

queryClient.getQueryState

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

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

Options

  • queryKey?: QueryKey：查询键
  • filters?: QueryFilters：查询过滤器

queryClient.setQueriesData

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

queryClient.setQueriesData(queryKey | filters, updater)

Options

  • queryKey: QueryKey：查询键 | filters: QueryFilters：查询过滤器

    • 如果将 queryKey 作为第一个参数传递，则部分匹配此参数的 queryKey 将被更新
    • 如果传递了一个过滤器，则匹配过滤器的 queryKeys 将被更新

  • updater: TData | (oldData: TData | undefined) => TData

    • setQueryData 更新函数或新数据，将为每个匹配的 queryKey 调用

queryClient.invalidateQueries

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

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

Options

  • queryKey?: QueryKey:查询键

  • filters?: QueryFilters:查询过滤器

    • refetchType?: 'active' | 'inactive' | 'all' | 'none'

      • 默认为'active'
      • 当设置为 时active，只有匹配 refetch 谓词并且通过useQuery和朋友主动呈现的查询才会在后台重新获取
      • 当设置为 时inactive，只有匹配 refetch 谓词并且没有通过useQuery和朋友主动呈现的查询才会在后台重新获取
      • 当设置为 时all，所有匹配 refetch 谓词的查询都将在后台重新获取
      • 当设置为 时none，不会重新获取任何查询，并且与重新获取谓词匹配的查询将仅标记为无效

    • refetchPage: (page: TData, index: number, allPages: TData[]) => boolean

      • 仅适用于无限查询
      • 使用此函数可指定应重新获取哪些页面

  • options?: InvalidateOptions：

    • throwOnError?: boolean

      • 当设置为true时，如果任何查询重新获取任务失败，此方法将抛出。

    • cancelRefetch?: boolean

      • 默认为true

        • 默认情况下，当前正在运行的请求将在发出新请求之前被取消

      • 设置为false时，如果已经有请求在运行，则不会重新获取。

queryClient.refetchQueries

该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(['posts'], { type: 'active' })


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

Options

  • queryKey?: QueryKey：查询键

  • filters?: QueryFilters：查询过滤器

    • refetchPage: (page: TData, index: number, allPages: TData[]) => boolean

      • 仅适用于无限查询
      • 使用此函数指定应重新获取哪些页面

  • options?: RefetchOptions：

    • throwOnError?: boolean

      • 当设置为true时，如果任何查询重新获取任务失败，此方法将抛出。

    • cancelRefetch?: boolean

      • 默认为true

        • 默认情况下，当前正在运行的请求将在发出新请求之前被取消

      • 设置为false时，如果已经有请求在运行，则不会重新获取。

Returns

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

queryClient.cancelQueries

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

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

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

Options

  • queryKey?: QueryKey：查询键
  • filters?: QueryFilters：查询过滤器

Returns

此方法不返回任何内容

queryClient.removeQueries

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

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

Options

  • queryKey?: QueryKey：查询键
  • filters?: QueryFilters：查询过滤器

Returns

此方法不返回任何内容

queryClient.resetQueries

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

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

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

Options

  • queryKey?: QueryKey：查询键

  • filters?: QueryFilters：查询过滤器

    • refetchPage: (page: TData, index: number, allPages: TData[]) => boolean

      • 仅适用于无限查询
      • 使用此函数指定应重新获取哪些页面

  • options?: ResetOptions：

    • throwOnError?: boolean

      • 当设置为true时，如果任何查询重新获取任务失败，此方法将抛出。

    • cancelRefetch?: boolean

      • 默认为true

        • 默认情况下，当前正在运行的请求将在发出新请求之前被取消

      • 设置为false时，如果已经有请求在运行，则不会重新获取。

Returns

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

queryClient.isFetching

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

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

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

Options

  • queryKey?: QueryKey：查询键
  • filters?: QueryFilters：查询过滤器

Returns

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

queryClient.isMutating

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

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

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

Options

  • filters: MutationFilters：变异过滤器 Returns

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

queryClient.getLogger

该getLogger方法返回创建客户端时设置的记录器。

const logger = queryClient.getLogger()

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(['posts'])
}

Options

  • queryKey: QueryKey：查询键
  • 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(['addPost'])
}

Options

  • mutationKey: string | 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()

QueryClientProvider

使用QueryClientProvider组件连接并提供一个QueryClient到你的应用程序：

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

const queryClient = new QueryClient()

function App() {
  return <QueryClientProvider client={queryClient}>...</QueryClientProvider>
}

Options

  • client: QueryClient

    • 必需的
    • 要提供的 QueryClient 实例

  • contextSharing: boolean

    • 默认为false
    • 将此设置true为启用上下文共享，这将在窗口中共享上下文的第一个和至少一个实例，以确保如果 React Query 用于不同的包或微前端，它们都将使用相同的上下文实例，而不管模块如何范围界定

  • context?: React.Context<QueryClient | undefined>

    • 使用它来使用自定义的 React Query 上下文。否则，将使用defaultContext

useQueryClient

useQueryClient钩子返回当前QueryClient实例。

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

const queryClient = useQueryClient()

QueryCache

QueryCache是React Query的存储机制。它存储它包含的所有数据、元信息和查询状态。 通常，您不会直接与QueryCache交互，而是将QueryClient用于特定的缓存。

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

const queryCache = new QueryCache({
  onError: error => {
    console.log(error)
  },
  onSuccess: data => {
    console.log(data)
  }
})

const query = queryCache.find('posts')

其可用的方法有：

  • find
  • findAll
  • subscribe
  • clear

Options

  • onError?: (error: unknown, query: Query) => void

    • 可选的
    • 如果某些查询遇到错误，将调用此函数。

  • onSuccess?: (data: unknown, query: Query) => void

    • 可选的
    • 如果某些查询成功，将调用此函数。

全局回调

QueryCache 上的onError和onSuccess回调可用于在全局级别上处理这些事件。它们与提供给 QueryClient 不同的defaultOptions，因为：

  • defaultOptions可以被每个 Query 覆盖——将始终调用全局回调。
  • defaultOptions每个 Observer 都会调用一次回调，而每个 Query 只会调用一次全局回调。

queryCache.find

find是一种稍微高级的同步方法，可用于从缓存中获取现有查询实例。该实例不仅包含查询的所有状态，还包含所有实例以及查询的底层内容。如果查询不存在，将返回undefined。

注意：大多数应用程序通常不需要此功能，但在极少数情况下需要有关查询的更多信息时会派上用场（例如，查看 query.state.dataUpdatedAt 时间戳以确定查询是否足够新鲜以用作初始值）

const query = queryCache.find(queryKey)

Options

  • queryKey?: QueryKey：查询键
  • filters?: QueryFilters：查询过滤器

Returns

  • Query

    • 缓存中的查询实例

queryCache.findAll

findAll是更高级的同步方法，可用于从缓存中获取部分匹配查询键的现有查询实例。如果查询不存在，将返回空数组。

注意：大多数应用程序通常不需要此功能，但在极少数情况下需要有关查询的更多信息时会派上用场

const queries = queryCache.findAll(queryKey)

Options

  • queryKey?: QueryKey：查询键
  • filters?: QueryFilters：查询过滤器

Returns

  • Query[]

    • 从缓存中查询实例

queryCache.subscribe

该subscribe方法可用于订阅整个查询缓存，并被告知对缓存的安全/已知更新，例如查询状态更改或查询正在更新、添加或删除

const callback = event => {
  console.log(event.type, event.query)
}

const unsubscribe = queryCache.subscribe(callback)

Options

  • callback: (event: QueryCacheNotifyEvent) => void

    • 每当查询缓存通过其跟踪的更新机制进行更新时，该函数会被调用（如query.setState,queryClient.removeQueries,等)。不鼓励对缓存进行超出范围的修改，并且不会触发订阅回调

Returns

  • unsubscribe: Function => void

    • 此函数将从查询缓存中取消订阅回调。

queryCache.clear

该clear方法可用于完全清除缓存并重新开始。

queryCache.clear()

MutationCache

MutationCache是突变的存储。 通常，您不会直接与 MutationCache 交互，而是使用QueryClient.

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

const mutationCache = new MutationCache({
  onError: error => {
    console.log(error)
  },
  onSuccess: data => {
    console.log(data)
  },
})

其可用的方法有：

  • getAll
  • subscribe
  • clear

Options

  • onError?: (error: unknown, variables: unknown, context: unknown, mutation: Mutation) => void

    • 可选的
    • 如果某些突变遇到错误，将调用此函数。

  • onSuccess?: (data: unknown, variables: unknown, context: unknown, mutation: Mutation) => void

    • 可选的
    • 如果某些突变成功，将调用此函数。

  • onMutate?: (variables: unknown, mutation: Mutation) => void

    • 可选的
    • 此函数将在某些突变执行之前被调用。

全局回调

MutationCache上的onError,onSuccess和onMutate回调可用于在全局级别上处理这些事件。它们与提供给 QueryClient 的defaultOptions不同，因为：

  • defaultOptions可以被每个 Mutation 覆盖——将始终调用全局回调。
  • onMutate不允许返回上下文值。

mutationCache.getAll

getAll返回缓存中的所有突变。

注意：大多数应用程序通常不需要此功能，但在极少数情况下需要有关突变的更多信息时会派上用场

const mutations = mutationCache.getAll()

Returns

  • Mutation[]

    • 缓存中的突变实例

mutationCache.subscribe

该subscribe方法可用于订阅整个突变缓存，并被告知对缓存的安全/已知更新，例如突变状态更改或更新、添加或删除的突变。

const callback = event => {
  console.log(event.type, event.mutation)
}

const unsubscribe = mutationCache.subscribe(callback)

Options

  • callback: (mutation?: MutationCacheNotifyEvent) => void

    • 每当更新时，都会使用突变缓存调用此函数。

Returns

  • unsubscribe: Function => void

    • 此函数将从突变缓存中取消订阅回调。

mutationCache.clear

该clear方法可用于完全清除缓存并重新开始。

mutationCache.clear()

QueryObserver

QueryObserver可用于观察查询并在查询之间切换。

const observer = new QueryObserver(queryClient, { queryKey: ['posts'] })

const unsubscribe = observer.subscribe(result => {
  console.log(result)
  unsubscribe()
})

Options

  • QueryObserver的选项与useQuery的完全相同。

InfiniteQueryObserver

InfiniteQueryObserver可以用来观察和切换无限查询。

const observer = new InfiniteQueryObserver(queryClient, {
  queryKey: ['posts'],
  queryFn: fetchPosts,
  getNextPageParam: (lastPage, allPages) => lastPage.nextCursor,
  getPreviousPageParam: (firstPage, allPages) => firstPage.prevCursor,
})

const unsubscribe = observer.subscribe(result => {
  console.log(result)
  unsubscribe()
})

Options

  • InfiniteQueryObserver的选项和useInfiniteQuery的完全相同。

QueriesObserver

QueriesObserver可用于观察多个查询。

const observer = new QueriesObserver(queryClient, [
  { queryKey: ['post', 1], queryFn: fetchPost },
  { queryKey: ['post', 2], queryFn: fetchPost },
])

const unsubscribe = observer.subscribe(result => {
  console.log(result)
  unsubscribe()
})

Options

  • QueriesObserver的选项与useQueries的完全相同。

QueryErrorResetBoundary

在查询中使用suspense或useErrorBoundaries时，您需要一种方法让查询知道您想在发生错误后重新渲染时重试。使用该QueryErrorResetBoundary组件，您可以重置组件边界内的任何查询错误。

import { QueryErrorResetBoundary } from '@tanstack/react-query'
import { ErrorBoundary } from 'react-error-boundary'

const App: React.FC = () => (
  <QueryErrorResetBoundary>
    {({ reset }) => (
      <ErrorBoundary
        onReset={reset}
        fallbackRender={({ resetErrorBoundary }) => (
          <div>
            There was an error!
            <Button onClick={() => resetErrorBoundary()}>Try again</Button>
          </div>
        )}
      >
        <Page />
      </ErrorBoundary>
    )}
  </QueryErrorResetBoundary>
)
avatar
文章
阅读
粉丝
相关推荐
缓存冲突：SWR vs. TanStack Query for React
1.3k阅读
 · 
7点赞
Remix 多页面数据流与 axios 的单页面的数据流的区别
1.1k阅读
 · 
1点赞
react-hook-form
383阅读
 · 
2点赞
react-query从拒绝到拥抱
5.5k阅读
 · 
24点赞
讲解下query-react的竞品swr具体使用
536阅读
 · 
3点赞