​​​​

React Query通常被描述为React缺少的数据获取库，但从技术上讲，它使React应用程序中的获取、缓存、同步和更新服务器状态变得轻而易举。

useQuery是react-query最常用的hook，没有之一。

一、使用方式

const {
    
    
   data,
   dataUpdatedAt,
   error,
   errorUpdatedAt,
   failureCount,
   isError,
   isFetched,
   isFetchedAfterMount,
   isFetching,
   isIdle,
   isLoading,
   isLoadingError,
   isPlaceholderData,
   isPreviousData,
   isRefetchError,
   isRefetching,
   isStale,
   isSuccess,
   refetch,
   remove,
   status,
 } = useQuery(queryKey, queryFn?, {
    
    
   cacheTime,
   enabled,
   initialData,
   initialDataUpdatedAt
   isDataEqual,
   keepPreviousData,
   meta,
   notifyOnChangeProps,
   notifyOnChangePropsExclusions,
   onError,
   onSettled,
   onSuccess,
   placeholderData,
   queryKeyHashFn,
   refetchInterval,
   refetchIntervalInBackground,
   refetchOnMount,
   refetchOnReconnect,
   refetchOnWindowFocus,
   retry,
   retryOnMount,
   retryDelay,
   select,
   staleTime,
   structuralSharing,
   suspense,
   useErrorBoundary,
 })
 
 // or using the object syntax
 
 const result = useQuery({
    
    
   queryKey,
   queryFn,
   enabled,
 })

二、Options

• queryKey: string | unknown[]

  • 必填项
  • 用于该查询的查询键，并且对查询的数据来说它是唯一的
  • 键值可以像字符串一样简单，也可以像由许多字符串和嵌套对象组成的数组一样复杂
  • 当此键更改时，查询将自动更新（只要enabled未设置为false）

  queryKey作为唯一键值将在React Query内部用于在整个程序中重新获取数据、缓存和共享查询，因此你可以使用特定的key来缓存某些特定的接口数据。而且queryKey的更改会导致查询更新，因此你可以将接口字段设置为queryKey，比如：useQuery([‘todos’, { page, status }], …)

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

  • 必填项，（当定义默认查询函数后可不填）
  • 查询将用于请求数据的函数。
  • 接收具有以下变量的QueryFunctionContext对象
  • 必须返回将解析数据或抛出错误的承诺

• enabled: boolean

  • false时queryFn将不会自动执行
  • 有时候我们可以根据特定参数来判断是否执行该查询

 // 获取用户
 const {
    
     data: user } = useQuery(['user', email], getUserByEmail)
 
 const userId = user?.id
 
 // 获取该用户的项目
 const {
    
     isIdle, data: projects } = useQuery(
   ['projects', userId],
   getProjectsByUser,
   {
    
    
     // 在userId获取到之前，查询不会执行
     enabled: !!userId,
   }
 )

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

  • true: 查询失败后将无限重复查询
  • false: 默认情况下不会重试失败的查询
  • number: 失败的查询将重试，直到失败的查询计数满足该数字

• retryOnMount: boolean

  • 默认为true，如果设置为false，则在组件加载时如果有错误，将不会重新查询

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

  • 重新查询的延迟时间

• staleTime: number | Infinity

  • 可选，默认为0
  • 数据被认为过期后的时间（毫秒）
  • 如果设置为Infinity，数据将永远不会被认为过期

• cacheTime: number | Infinity

  • 默认值为5分钟
  • 查询的缓存数据未使用超过该时长后，缓存数据将被回收
  • 如果设置为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，则窗口获得焦点时，查询将不会重新获取
  • 如果设置为“始终”，则窗口获得焦点时，询将始终重新获取
  • 如果设置为函数，则将使用查询执行该函数以计算值

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

  • 可选，默认为true
  • 如果设置为true，则如果数据过期，则查询将在重新连接时重新执行
  • 如果设置为false，则在重新连接时查询将不会重新执行
  • 如果设置为“始终”，则查询将始终在重新连接时重新连接
  • 如果设置为函数，则将使用查询执行该函数以计算值

• notifyOnChangeProps: string[] | “tracked”

  • 可选
  • 如果设置，则仅当列出的任何属性发生更改时，组件才会重新渲染
  • 例如，如果设置为[‘data’，‘error’]，则只有当数据或错误属性更改时，组件才会重新渲染。
  • 如果设置为“tracked”，则将跟踪对属性的访问，并且只有在跟踪的属性之一发生更改时，组件才会重新渲染。

• notifyOnChangePropsExclusions: string[]

  • 可选
  • 如果设置，则如果列出的任何属性发生更改，组件将不会重新渲染。
  • 例如，如果设置为[‘isTale’]，当isStale属性更改时，组件将不会重新渲染。

• onSuccess: (data: TData) => void

  • 可选
  • 每当查询成功获取新数据或通过setQueryData更新缓存时，此函数都会执行

• 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

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

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

  • 可选
  • 如果设置了该值，则该值将用作initialData自身上次更新的时间（以毫秒为单位）。

• placeholderData: TData | () => TData

  • 可选
  • 如果设置了该值，则当查询仍在加载数据中且未提供initialData时，该值将用作此特定查询观察者的占位符数据。
  • 占位符数据未持久化到缓存

• keepPreviousData: boolean

  • 可选，默认为false
  • 如果设置，则在获取新数据时，将保留所有以前的数据，因为查询键已更改

• structuralSharing: boolean

  • 可选，默认为true
  • 如果设置为false，将禁用查询结果之间的结构共享

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

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

• meta: Record<string, unknown>

  • 可选
  • 如果已设置，则存储有关查询缓存项的附加信息，可根据需要使用这些信息。它将在查询可用的任何地方都可以访问，并且也是提供给queryFn的QueryFunctionContext的一部分

三、Returns

• status: String

  • idle: 空闲。只有在使用enabled:false初始化查询并且没有可用的初始数据时，才会出现这种情况
  • loading: 加载中。这意味着没有缓存数据，并且查询当前正在获取，例如isFetching==true
  • error: 查询返回结果抛出错误
  • success: 如果查询已收到无错误的响应并准备好显示其数据，则为成功。查询上对应的数据属性是从成功获取中接收的数据，或者如果查询的enabled属性设置为false并且尚未获取，则数据是初始化时提供给查询的第一个initialData

• isIdle: boolean

  • 从上述 status 变量衍射的布尔值，为方便起见提供

• isLoading: boolean

  • 从上述 status 变量衍射的布尔值，为方便起见提供

• isSuccess: boolean

  • 从上述 status 变量衍射的布尔值，为方便起见提供

• isError: boolean

  • 从上述 status 变量衍射的布尔值，为方便起见提供

• isLoadingError: boolean

  • 如果第一次执行时查询失败，则为true

• isRefetchError: boolean

  • 如果重新查询时查询失败，则为true

• data: TData

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

• dataUpdatedAt: number

  • 查询最近返回状态为“成功”的时间戳

• error: null | TError

  • 默认 null
  • 如果抛出错误，则返回查询的错误对象。

• errorUpdatedAt: number

  • 查询最近返回状态为“error”的时间戳

• isStale: boolean

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

• isPlaceholderData: boolean

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

• isPreviousData: boolean

  • 当设置keepPreviousData并返回上一个查询的数据时，将为true

• isFetched: boolean

  • 如果已执行查询，则为true

• isFetchedAfterMount: boolean

  • 如果在加载组件后提取了查询，则为true
  • 此属性可用于不显示任何以前缓存的数据

• isFetching: boolean

  • 无论何时请求正在运行，都是true，这包括初始加载和后台引用。
  • 如果查询当前正在获取（包括后台获取），则为true。

• isRefetching: boolean

  • 当后台重新加载正在进行时（不包括初始加载）为true
  • 与 (isFetching && !isLoading) 相同

• failureCount: number

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

• errorUpdateCount: number

  • 所有错误的总和

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

  • 手动重新执行查询的函数
  • 如果查询错误，则只记录错误。如果希望抛出错误，请传递throwOnError:true选项
  • 如果cancelRefetch为true，则在发出新请求之前将取消当前请求

• remove: () => void

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