TanStack Query V4 异步状态管理--翻译中文版

·  阅读 1401
TanStack Query V4 异步状态管理--翻译中文版

React Query V4 API翻译参考

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

useQuery

const {
  data,
  dataUpdatedAt,
  error,
  errorUpdatedAt,
  failureCount,
  isError,
  isFetched,
  isFetchedAfterMount,
  isFetching,
  isPaused,
  isLoading,
  isLoadingError,
  isPlaceholderData,
  isPreviousData,
  isRefetchError,
  isRefetching,
  isStale,
  isSuccess,
  refetch,
  remove,
  status,
  fetchStatus,
} = useQuery(queryKey, queryFn?, {
  cacheTime,
  enabled,
  networkMode,
  initialData,
  initialDataUpdatedAt,
  isDataEqual,
  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
    • 必须返回一个将解析数据或抛出错误的承诺。数据不能是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 分钟)或InfinitySSR 期间
    • 未使用/非活动的缓存数据在内存中保留的时间(以毫秒为单位)。当查询的缓存变得未使用或不活动时,该缓存数据将在此持续时间后被垃圾回收。当指定不同的缓存时间时,将使用最长的缓存时间
    • 如果设置为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'],则组件只会在dataerror属性更改时重新渲染
    • 如果设置为"all",组件将选择退出智能跟踪并在查询更新时重新呈现
    • 默认情况下,对属性的访问将被跟踪,并且只有当被跟踪的属性之一发生更改时,组件才会重新渲染
  • onSuccess: (data: TData) => void

    • 可选的
    • 每当查询成功获取新数据时,都会触发此函数
  • onError: (error: TError) => void

    • 可选的
    • 如果查询遇到错误,此函数将触发并传递错误
  • onSettled: (data?: TData, error?: TError) => void

    • 可选的
    • 该函数将在查询成功获取或出现错误的任何时候触发,并传递数据或错误
  • select: (data: TData) => unknown

    • 可选的
    • 该选项可用于转换或选择查询函数返回的部分数据
  • suspense: boolean

    • 可选的
    • 将此设置true为启用悬疑模式
    • true,当status === 'loading'时,useQuery会挂起
    • true,当status === 'error'时,useQuery会抛出运行时错误
  • 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

    • 可选的
    • 此函数应返回布尔值,指示是使用原数据(true)还是新数据(false)作为查询的解析数据
  • structuralSharing: boolean

    • 可选的
    • 默认为true
    • 如果设置为false,将禁用查询结果之间的结构共享
  • useErrorBoundary: undefined | boolean | (error: TError, query: Query) => boolean

    • 默认为全局查询配置的useErrorBoundary值,即undefined
    • 如果您希望在渲染阶段引发错误并传播到最近的错误边界,请将其设置为true
    • 将此设置false可以禁用suspense将错误抛出到错误边界的默认行为
    • 如果设置为函数,它将传递错误和查询,它应该返回一个布尔值,指示是在错误边界中显示错误(true)还是返回错误状态(false
  • meta: Record<string, unknown>

    • 可选的
    • 如果设置,将存储查询缓存条目上的额外信息,以便在需要时使用。它可以在任何query可用的地方访问,并且也是QueryFunctionContext提供给queryFn
  • context?: React.Context<QueryClient | undefined>

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

Returns

  • status: String

    • 将会:

      • 如果查询处于“硬”加载状态,则返回loading。这意味着没有缓存数据并且查询当前正在获取,例如isFetching === true
      • 如果查询尝试导致错误,则返回error。对应的error属性具有从尝试获取中收到的错误
      • 如果查询收到没有错误的响应并准备显示其数据,则返回success。查询上的相应data属性是从成功获取中接收到的数据,或者如果查询的enabled属性设置为false但尚未获取,则数据是在初始化时提供给查询的第一个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: booleanfetchNextPage相同
  • 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

    • 可选的
    • 此函数将在突变函数被触发之前触发,并传递与突变函数接收到的相同的变量
    • 在希望突变成功时对资源执行乐观更新
    • 如果发生突变失败,从此函数返回的值将传递给onErroronSettled函数,并且可用于回滚乐观更新
  • 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可用,就可以访问它(例如MutationCacheonError,onSuccess功能)
  • context?: React.Context<QueryClient | undefined>

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

Returns

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

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

    • variables: TVariables

      • 可选的
      • 传递给mutationFnvariables对象
    • 其余的选项扩展了上述useMutation钩子中描述的相同选项

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

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

    • 类似于mutate,但返回一个可以等待的承诺
  • status: string

    • 将会:

      • idle 突变函数执行前的初始状态
      • loading 如果突变当前正在执行
      • error 如果最后一次突变尝试导致错误
      • success 如果最后一次突变尝试成功
  • isIdleisLoadingisSuccessisError: 来自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早,则将返回缓存中的数据。否则它将尝试获取最新数据。

使用fetchQuerysetQueryData之间的区别在于,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; 严格适用于 useQueryuseInfiniteQuery。您可以查看源代码以获得更清晰的信息。

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代替。

使用setQueryDatafetchQuery之间的区别在于,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 上的onErroronSuccess回调可用于在全局级别上处理这些事件。它们与提供给 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,onSuccessonMutate回调可用于在全局级别上处理这些事件。它们与提供给 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

在查询中使用suspenseuseErrorBoundaries时,您需要一种方法让查询知道您想在发生错误后重新渲染时重试。使用该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>
)
复制代码
收藏成功!
已添加到「」, 点击更改