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）
- 默认为全局查询配置的useErrorBoundary值，为 undefined
-
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
- 从缓存中删除查询的函数
扫一扫
1303
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
