useInfiniteQuery
概述
TypeScript
1function useInfiniteQuery<TQueryFnData, TError = Error, TData = InfiniteData<TQueryFnData, unknown>, TQueryKey extends readonly unknown[] = readonly unknown[], TPageParam = unknown>(options: DefinedInitialDataInfiniteOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>, queryClient?: QueryClient): DefinedUseInfiniteQueryResult<TData, TError>;2function useInfiniteQuery<TQueryFnData, TError = Error, TData = InfiniteData<TQueryFnData, unknown>, TQueryKey extends readonly unknown[] = readonly unknown[], TPageParam = unknown>(options: UndefinedInitialDataInfiniteOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>, queryClient?: QueryClient): UseInfiniteQueryResult<TData, TError>;3function useInfiniteQuery<TQueryFnData, TError = Error, TData = InfiniteData<TQueryFnData, unknown>, TQueryKey extends readonly unknown[] = readonly unknown[], TPageParam = unknown>(options: UseInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>, queryClient?: QueryClient): UseInfiniteQueryResult<TData, TError>;DefinedInitialDataInfiniteOptions→DefinedUseInfiniteQueryResult：useInfiniteQuery的选项与useQuery完全相同，额外增加了initialPageParam、getNextPageParam、getPreviousPageParam和maxPages。UndefinedInitialDataInfiniteOptions→UseInfiniteQueryResult：useInfiniteQuery的选项与useQuery完全相同，额外增加了initialPageParam、getNextPageParam、getPreviousPageParam和maxPages。UseInfiniteQueryOptions→UseInfiniteQueryResult：useInfiniteQuery的选项与useQuery完全相同，额外增加了initialPageParam、getNextPageParam、getPreviousPageParam和maxPages。
调用签名
TypeScript
1function useInfiniteQuery<TQueryFnData, TError = Error, TData = InfiniteData<TQueryFnData, unknown>, TQueryKey extends readonly unknown[] = readonly unknown[], TPageParam = unknown>(options: DefinedInitialDataInfiniteOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>, queryClient?: QueryClient): DefinedUseInfiniteQueryResult<TData, TError>;定义于：packages/react-query/src/useInfiniteQuery.ts:63
useInfiniteQuery 的选项与 useQuery 完全相同，额外增加了 initialPageParam、getNextPageParam、getPreviousPageParam 和 maxPages。
当 initialData 已知被定义时，将选择此重载。
类型参数
TQueryFnData
TQueryFnData
TError
TError = Error
TData
TData = InfiniteData<TQueryFnData, unknown>
TQueryKey
TQueryKey extends readonly unknown[] = readonly unknown[]
TPageParam
TPageParam = unknown
参数
options
DefinedInitialDataInfiniteOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>
要使用的 DefinedInitialDataInfiniteOptions —— 即可传给 useInfiniteQuery 的所有选项，且 initialData 已知被定义。
queryClient?
使用此参数可指定自定义的 QueryClient；否则将使用最近上下文中的 QueryClient。
返回值
DefinedUseInfiniteQueryResult<TData, TError>
与 useQuery 具有相同的属性，并额外增加了 fetchNextPage、fetchPreviousPage、hasNextPage、hasPreviousPage、isFetchingNextPage 和 isFetchingPreviousPage。只要 select 未将 TData 修改为偏离其默认的 InfiniteData<TQueryFnData> 形状，data.pages 和 data.pageParams 也会被添加。
备注
请注意，命令式拉取调用（例如 fetchNextPage）可能会干扰默认的重新拉取行为，导致数据过期。请确保仅在响应用户操作时调用这些函数，或添加类似 hasNextPage && !isFetching 的条件判断。
参阅
infiniteQueryOptions，用于在 useInfiniteQuery 与 queryClient.infiniteQuery 等命令式 API 之间共享这些选项。
示例
TypeScript
1import { useInfiniteQuery } from '@tanstack/react-query'2 3function Projects() {4 // `data` is never `undefined`, thanks to `initialData` — even if a refetch fails, so the5 // list stays visible alongside the error.6 const { data, isError, error } = useInfiniteQuery({7 queryKey: ['projects'],8 queryFn: ({ pageParam }) => fetchProjects(pageParam),9 initialPageParam: 0,10 getNextPageParam: (lastPage) => lastPage.nextId,11 initialData: { pages: [], pageParams: [] },12 })13 14 return (15 <div>16 {isError ? <span>Error: {error.message}</span> : null}17 <ul>18 {data.pages.map((page) => page.projects.map((p) => <li key={p.id}>{p.name}</li>))}19 </ul>20 </div>21 )22}调用签名
TypeScript
1function useInfiniteQuery<TQueryFnData, TError = Error, TData = InfiniteData<TQueryFnData, unknown>, TQueryKey extends readonly unknown[] = readonly unknown[], TPageParam = unknown>(options: UndefinedInitialDataInfiniteOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>, queryClient?: QueryClient): UseInfiniteQueryResult<TData, TError>;定义于：packages/react-query/src/useInfiniteQuery.ts:186
useInfiniteQuery 的选项与 useQuery 完全相同，额外增加了 initialPageParam、getNextPageParam、getPreviousPageParam 和 maxPages。
类型参数
TQueryFnData
TQueryFnData
TError
TError = Error
TData
TData = InfiniteData<TQueryFnData, unknown>
TQueryKey
TQueryKey extends readonly unknown[] = readonly unknown[]
TPageParam
TPageParam = unknown
参数
options
UndefinedInitialDataInfiniteOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>
要使用的 UndefinedInitialDataInfiniteOptions —— 即可传给 useInfiniteQuery 的所有选项。
queryClient?
使用此参数可指定自定义的 QueryClient；否则将使用最近上下文中的 QueryClient。
返回值
UseInfiniteQueryResult<TData, TError>
与 useQuery 具有相同的属性，并额外增加了 fetchNextPage、fetchPreviousPage、hasNextPage、hasPreviousPage、isFetchingNextPage 和 isFetchingPreviousPage。只要 select 未将 TData 修改为偏离其默认的 InfiniteData<TQueryFnData> 形状，data.pages 和 data.pageParams 也会被添加。
备注
请注意，命令式拉取调用（例如 fetchNextPage）可能会干扰默认的重新拉取行为，导致数据过期。请确保仅在响应用户操作时调用这些函数，或添加类似 hasNextPage && !isFetching 的条件判断。
参阅
infiniteQueryOptions，用于在 useInfiniteQuery 与 queryClient.infiniteQuery 等命令式 API 之间共享这些选项。
示例
通过点击“加载更多”按钮获取下一页：
TypeScript
1import { useInfiniteQuery } from '@tanstack/react-query'2 3function Projects() {4 const { data, isPending, isError, error, fetchNextPage, hasNextPage, isFetching, isFetchingNextPage } =5 useInfiniteQuery({6 queryKey: ['projects'],7 queryFn: ({ pageParam }) => fetchProjects(pageParam),8 initialPageParam: 0,9 getNextPageParam: (lastPage) => lastPage.nextId,10 })11 12 if (isPending) return 'Loading...'13 if (isError) return <span>Error: {error.message}</span>14 15 return (16 <>17 <ul>18 {data.pages.map((page) =>19 page.projects.map((project) => <li key={project.id}>{project.name}</li>),20 )}21 </ul>22 <button23 onClick={() => fetchNextPage()}24 disabled={!hasNextPage || isFetching}25 >26 {isFetchingNextPage27 ? 'Loading more...'28 : hasNextPage29 ? 'Load More'30 : 'Nothing more to load'}31 </button>32 </>33 )34}利用列表末尾的哨兵元素上的 IntersectionObserver，在用户滚动时自动获取下一页：
TypeScript
1import { useInfiniteQuery } from '@tanstack/react-query'2import { useEffect, useRef } from 'react'3 4function Projects() {5 const {6 data,7 isPending,8 isError,9 error,10 fetchNextPage,11 hasNextPage,12 isFetching,13 isFetchingNextPage,14 } = useInfiniteQuery({15 queryKey: ['projects'],16 queryFn: ({ pageParam }) => fetchProjects(pageParam),17 initialPageParam: 0,18 getNextPageParam: (lastPage) => lastPage.nextId,19 })20 21 const sentinelRef = useRef<HTMLDivElement>(null)22 23 useEffect(() => {24 const sentinel = sentinelRef.current25 if (sentinel == null || !hasNextPage || isFetching) return26 27 const observer = new IntersectionObserver(([entry]) => {28 if (entry?.isIntersecting) fetchNextPage()29 })30 observer.observe(sentinel)31 32 return () => observer.disconnect()33 }, [hasNextPage, isFetching, fetchNextPage])34 35 if (isPending) return 'Loading...'36 if (isError) return <span>Error: {error.message}</span>37 38 return (39 <>40 <ul>41 {data.pages.map((page) =>42 page.projects.map((project) => <li key={project.id}>{project.name}</li>),43 )}44 </ul>45 <div ref={sentinelRef}>{isFetchingNextPage ? 'Loading more...' : null}</div>46 </>47 )48}调用签名
TypeScript
1function useInfiniteQuery<TQueryFnData, TError = Error, TData = InfiniteData<TQueryFnData, unknown>, TQueryKey extends readonly unknown[] = readonly unknown[], TPageParam = unknown>(options: UseInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>, queryClient?: QueryClient): UseInfiniteQueryResult<TData, TError>;定义于：packages/react-query/src/useInfiniteQuery.ts:338
useInfiniteQuery 的选项与 useQuery 完全相同，额外增加了 initialPageParam、getNextPageParam、getPreviousPageParam 和 maxPages。
类型参数
TQueryFnData
TQueryFnData
TError
TError = Error
TData
TData = InfiniteData<TQueryFnData, unknown>
TQueryKey
TQueryKey extends readonly unknown[] = readonly unknown[]
TPageParam
TPageParam = unknown
参数
options
UseInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>
要使用的 UseInfiniteQueryOptions —— 即可传给 useInfiniteQuery 的所有选项。
queryClient?
使用此参数可指定自定义的 QueryClient；否则将使用最近上下文中的 QueryClient。
返回值
UseInfiniteQueryResult<TData, TError>
与 useQuery 具有相同的属性，并额外增加了 fetchNextPage、fetchPreviousPage、hasNextPage、hasPreviousPage、isFetchingNextPage 和 isFetchingPreviousPage。只要 select 未将 TData 修改为偏离其默认的 InfiniteData<TQueryFnData> 形状，data.pages 和 data.pageParams 也会被添加。
备注
请注意，命令式拉取调用（例如 fetchNextPage）可能会干扰默认的重新拉取行为，导致数据过期。请确保仅在响应用户操作时调用这些函数，或添加类似 hasNextPage && !isFetching 的条件判断。
参阅
infiniteQueryOptions，用于在 useInfiniteQuery 与 queryClient.infiniteQuery 等命令式 API 之间共享这些选项。
示例
通过点击“加载更多”按钮获取下一页：
TypeScript
1import { useInfiniteQuery } from '@tanstack/react-query'2 3function Projects() {4 const { data, isPending, isError, error, fetchNextPage, hasNextPage, isFetching, isFetchingNextPage } =5 useInfiniteQuery({6 queryKey: ['projects'],7 queryFn: ({ pageParam }) => fetchProjects(pageParam),8 initialPageParam: 0,9 getNextPageParam: (lastPage) => lastPage.nextId,10 })11 12 if (isPending) return 'Loading...'13 if (isError) return <span>Error: {error.message}</span>14 15 return (16 <>17 <ul>18 {data.pages.map((page) =>19 page.projects.map((project) => <li key={project.id}>{project.name}</li>),20 )}21 </ul>22 <button23 onClick={() => fetchNextPage()}24 disabled={!hasNextPage || isFetching}25 >26 {isFetchingNextPage27 ? 'Loading more...'28 : hasNextPage29 ? 'Load More'30 : 'Nothing more to load'}31 </button>32 </>33 )34}利用列表末尾的哨兵元素上的 IntersectionObserver，在用户滚动时自动获取下一页：
TypeScript
1import { useInfiniteQuery } from '@tanstack/react-query'2import { useEffect, useRef } from 'react'3 4function Projects() {5 const {6 data,7 isPending,8 isError,9 error,10 fetchNextPage,11 hasNextPage,12 isFetching,13 isFetchingNextPage,14 } = useInfiniteQuery({15 queryKey: ['projects'],16 queryFn: ({ pageParam }) => fetchProjects(pageParam),17 initialPageParam: 0,18 getNextPageParam: (lastPage) => lastPage.nextId,19 })20 21 const sentinelRef = useRef<HTMLDivElement>(null)22 23 useEffect(() => {24 const sentinel = sentinelRef.current25 if (sentinel == null || !hasNextPage || isFetching) return26 27 const observer = new IntersectionObserver(([entry]) => {28 if (entry?.isIntersecting) fetchNextPage()29 })30 observer.observe(sentinel)31 32 return () => observer.disconnect()33 }, [hasNextPage, isFetching, fetchNextPage])34 35 if (isPending) return 'Loading...'36 if (isError) return <span>Error: {error.message}</span>37 38 return (39 <>40 <ul>41 {data.pages.map((page) =>42 page.projects.map((project) => <li key={project.id}>{project.name}</li>),43 )}44 </ul>45 <div ref={sentinelRef}>{isFetchingNextPage ? 'Loading more...' : null}</div>46 </>47 )48}一个在 postId 被设置前处于禁用状态且类型安全的查询 —— 将 skipToken 作为 queryFn 传入，而非设置 enabled: false：
TypeScript
1import { skipToken, useInfiniteQuery } from '@tanstack/react-query'2 3function Comments({ postId }: { postId: string | undefined }) {4 // Use `isLoading`, not `isPending`, so the loading state doesn't show while the query is disabled.5 const { data, isLoading, isError, error } = useInfiniteQuery({6 queryKey: ['post', postId, 'comments'],7 queryFn:8 postId != null9 ? ({ pageParam }) => fetchComments(postId, pageParam)10 : skipToken,11 initialPageParam: 0,12 getNextPageParam: (lastPage) => lastPage.nextId,13 })14 15 if (postId == null) return 'Select a post'16 if (isLoading) return 'Loading...'17 if (isError) return <span>Error: {error.message}</span>18 19 return (20 <ul>21 {data?.pages.map((page) => page.comments.map((c) => <li key={c.id}>{c.text}</li>))}22 </ul>23 )24}参数
options
UseInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>
要使用的 UseInfiniteQueryOptions —— 即可传给 useInfiniteQuery 的所有选项。
options 属性
| 属性 | 类型 | 默认值 | 描述 |
|---|---|---|---|
enabled? |
| false | true | ((query: Query<TQueryFnData, TError, InfiniteData<TQueryFnData, TPageParam>, TQueryKey>) => boolean) |
true |
将此项设为 false 或返回 false 的函数，可禁用查询挂载或查询键变更时的自动重新拉取。如需重新拉取查询，请使用 useQuery 实例返回的 refetch 方法。接受布尔值或返回布尔值的函数。 |
gcTime? |
number |
undefined |
未使用/非活跃缓存数据在内存中保留的毫秒数。当某个查询的缓存变为未使用或非活跃状态后，该缓存数据将在该持续时间后被垃圾回收。若指定了多个垃圾回收时间，则采用最长的那个。设为 Infinity 将禁用垃圾回收。默认为 5 * 60 * 1000（5 分钟），服务端渲染（SSR）期间默认为 Infinity。注意：受 setTimeout 的 32 位有符号整数延迟限制，最大允许时间为约 24 天——参见 timeoutManager.setTimeoutProvider 获取变通方案。 |
getNextPageParam |
(lastPage: TQueryFnData, allPages: TQueryFnData[], lastPageParam: TPageParam, allPageParams: TPageParam[]) => TPageParam | null | undefined |
undefined |
可设置此函数以自动获取无限查询的下一页游标。其结果还将用于确定 hasNextPage 的值。 |
getPreviousPageParam? |
(firstPage: TQueryFnData, allPages: TQueryFnData[], firstPageParam: TPageParam, allPageParams: TPageParam[]) => TPageParam | null | undefined |
undefined |
可设置此函数以自动获取无限查询的上一页游标。其结果还将用于确定 hasPreviousPage 的值。 |
initialData? |
| InfiniteData<TQueryFnData, TPageParam> | (() => | InfiniteData<TQueryFnData, TPageParam> | undefined) |
undefined |
若设置此项，该值将作为查询缓存的初始数据（前提是该查询尚未创建或缓存）。若设为函数，该函数将在共享/根查询初始化期间仅执行一次，且需同步返回初始数据。默认情况下，初始数据被视为过期，除非已设置 staleTime。initialData 会被持久化到缓存中。 |
initialDataUpdatedAt? |
number | (() => number | undefined) |
undefined |
若设置此项，该值将作为 initialData 本身最后更新的时间（毫秒）。 |
initialPageParam |
TPageParam |
undefined |
当无限查询尚无任何页时，用于起始的页码参数。它将作为 queryFn 的 pageParam 参数传入第一页；后续每一页则使用 getNextPageParam 或 getPreviousPageParam 返回的值。该参数仅在查询尚无页时生效：一旦存在第一页，重新拉取将从该页自身的参数开始。 |
maxPages? |
number |
undefined |
无限查询的数据中最多存储的页数。 |
meta? |
Record<string, unknown> |
undefined |
存储在每个查询上的额外负载。可使用此属性传递可在其他位置使用的附加信息。 |
networkMode? |
"online" | "always" | "offlineFirst" |
'online' |
控制查询是否允许基于当前网络连接状态运行。详见 网络模式。 |
notifyOnChangeProps? |
| ( | "error" | "data" | "isError" | "isPending" | "isLoading" | "isLoadingError" | "isRefetchError" | "isSuccess" | "isPlaceholderData" | "status" | "dataUpdatedAt" | "errorUpdatedAt" | "failureCount" | "failureReason" | "errorUpdateCount" | "isFetched" | "isFetchedAfterMount" | "isFetching" | "isInitialLoading" | "isPaused" | "isRefetching" | "isStale" | "isEnabled" | "refetch" | "fetchStatus" | "fetchNextPage" | "fetchPreviousPage" | "hasNextPage" | "hasPreviousPage" | "isFetchNextPageError" | "isFetchingNextPage" | "isFetchPreviousPageError" | "isFetchingPreviousPage")[] | "all" | (() => | "all" | ( | "error" | "data" | "isError" | "isPending" | "isLoading" | "isLoadingError" | "isRefetchError" | "isSuccess" | "isPlaceholderData" | "status" | "dataUpdatedAt" | "errorUpdatedAt" | "failureCount" | "failureReason" | "errorUpdateCount" | "isFetched" | "isFetchedAfterMount" | "isFetching" | "isInitialLoading" | "isPaused" | "isRefetching" | "isStale" | "isEnabled" | "refetch" | "fetchStatus" | "fetchNextPage" | "fetchPreviousPage" | "hasNextPage" | "hasPreviousPage" | "isFetchNextPageError" | "isFetchingNextPage" | "isFetchPreviousPageError" | "isFetchingPreviousPage")[] | undefined) |
undefined |
若设置此项，组件仅在所列属性发生变更时重新渲染。设为 ['data', 'error'] 时，组件仅在 data 或 error 属性变更时重新渲染。设为 'all' 时，组件将在任意查询更新时重新渲染。设为函数时，该函数将被执行以计算属性列表。默认为 undefined，此时会自动追踪属性访问，组件仅在任一被追踪属性变更时重新渲染。 |
persister? |
(queryFn: (context: QueryFunctionContext<NoInfer<TQueryKey>, TPageParam>) => TQueryFnData | Promise<TQueryFnData>, context: object, query: Query) => TQueryFnData | Promise<TQueryFnData> |
undefined |
此选项可用于将查询结果持久化至外部存储，从而绕过实际调用 queryFn 的需要。适用于跨服务端/客户端边界持久化查询数据等场景。 |
placeholderData? |
| InfiniteData<TQueryFnData, TPageParam> | ((previousData: | InfiniteData<TQueryFnData, TPageParam> | undefined, previousQuery: | Query<InfiniteData<TQueryFnData, TPageParam>, TError, InfiniteData<TQueryFnData, TPageParam>, TQueryKey> | undefined) => | InfiniteData<TQueryFnData, TPageParam> | undefined) |
undefined |
若设置此项，该值将作为此特定查询观察者在查询仍处于 loading 数据状态且未提供 initialData 时的占位数据。 |
queryFn? |
| typeof skipToken | ((context: QueryFunctionContext<TQueryKey, TPageParam>) => TQueryFnData | Promise<TQueryFnData>) |
undefined |
查询用于请求数据的函数。必需，除非已通过 queryClient.setQueryDefaults 或 queryClient.setDefaultOptions 设置了默认查询函数。接收一个 QueryFunctionContext。必须返回一个 Promise，该 Promise 要么解析出数据，要么抛出错误。数据不能为 undefined。 |
queryHash? |
string |
undefined |
queryKey 的哈希形式，使用 queryKeyHashFn（或默认哈希函数）计算得出。在内部用作实际缓存键。 |
queryKey |
TQueryKey & object |
undefined |
此查询所用的查询键。查询键将被哈希为稳定哈希值。更多信息请参阅 查询键。只要 enabled 未设为 false，该键变更时查询将自动更新。 |
queryKeyHashFn? |
(queryKey: TQueryKey) => string |
undefined |
若指定此项，该函数将用于将 queryKey 哈希为字符串。 |
refetchInterval? |
| number | false | ((query: Query<TQueryFnData, TError, InfiniteData<TQueryFnData, TPageParam>, TQueryKey>) => number | false | undefined) |
false |
若设为数字，查询将以该毫秒频率持续重新拉取。若设为函数，该函数将使用最新数据和查询来计算频率。 |
refetchIntervalInBackground? |
boolean |
false |
若设为 true，查询将在其所在标签页/窗口处于后台时继续重新拉取。 |
refetchOnMount? |
| boolean | "always" | ((query: Query<TQueryFnData, TError, InfiniteData<TQueryFnData, TPageParam>, TQueryKey>) => boolean | "always") |
true |
若设为 true，查询在挂载时若数据已过期则重新拉取。若设为 false，将禁用查询的额外实例触发后台重新拉取。若设为 'always'，查询将在挂载时始终重新拉取（除非使用 staleTime: 'static'）。若设为函数，该函数将使用最新数据和查询来计算该值。 |
refetchOnReconnect? |
| boolean | "always" | ((query: Query<TQueryFnData, TError, InfiniteData<TQueryFnData, TPageParam>, TQueryKey>) => boolean | "always") |
undefined |
若设为 true，查询在网络重连时若数据已过期则重新拉取。若设为 false，查询在网络重连时不会重新拉取。若设为 'always'，查询将在网络重连时始终重新拉取（除非使用 staleTime: 'static'）。若设为函数，该函数将使用最新数据和查询来计算该值。默认为 true，除非 networkMode 为 'always'。 |
refetchOnWindowFocus? |
| boolean | "always" | ((query: Query<TQueryFnData, TError, InfiniteData<TQueryFnData, TPageParam>, TQueryKey>) => boolean | "always") |
true |
若设为 true，查询在窗口获得焦点时若数据已过期则重新拉取。若设为 false，查询在窗口获得焦点时不会重新拉取。若设为 'always'，查询将在窗口获得焦点时始终重新拉取（除非使用 staleTime: 'static'）。若设为函数，该函数将使用最新数据和查询来计算该值。 |
retry? |
| number | false | true | ((failureCount: number, error: TError) => boolean) |
undefined |
若为 false，失败的查询默认不重试。若为 true，失败的查询将无限重试。若设为整数（例如 3），失败的查询将重试直至失败次数达到该数值。若设为函数 (failureCount, error) => boolean，失败的查询将重试直至该函数返回 false。默认在客户端为 3，在服务端为 0。 |
retryDelay? |
number | ((failureCount: number, error: TError) => number) |
undefined |
此函数接收一个 retryAttempt 整数和实际错误，并返回下次尝试前应延迟的毫秒数。类似 attempt => Math.min(attempt > 1 ? 2 ** attempt * 1000 : 1000, 30 * 1000) 的函数应用指数退避策略；类似 attempt => attempt * 1000 的函数应用线性退避策略。默认为一个应用指数退避策略的函数，上限为 30 秒。 |
retryOnMount? |
| false | true | ((query: Query<TQueryFnData, TError, InfiniteData<TQueryFnData, TPageParam>, TQueryKey>) => boolean) |
true |
若设为 false，包含错误的查询在挂载时将不重试。若设为函数，该函数将使用查询来计算该值。 |
select? |
(data: InfiniteData) => TData |
undefined |
此选项可用于转换或选取查询函数返回数据的一部分。它会影响返回的 data 值，但不影响存储在查询缓存中的内容。select 函数仅在 data 发生变更，或 select 函数自身引用发生变更时运行。为优化性能，请对函数进行记忆化处理，使其引用在多次调用中保持稳定。 |
staleTime? |
| number | "static" | ((query: Query<TQueryFnData, TError, InfiniteData<TQueryFnData, TPageParam>, TQueryKey>) => number | "static") |
0 |
数据被视为过期后的毫秒数。若设为 Infinity，数据将永远不会被视为过期。若设为 'static'，数据将永远不会被视为过期。若设为函数，该函数将使用查询来计算 staleTime。 |
structuralSharing? |
boolean | ((oldData: unknown, newData: unknown) => unknown) |
true |
设为 false 可禁用查询结果之间的结构共享。设为一个接收旧数据和新数据并返回同类型已解析数据的函数，可实现自定义结构共享逻辑。 |
subscribed? |
boolean |
true |
设为 false 可取消此观察者对查询缓存更新的订阅。 |
throwOnError? |
| false | true | ((error: TError, query: Query<TQueryFnData, TError, InfiniteData<TQueryFnData, TPageParam>, TQueryKey>) => boolean) |
false |
是否应抛出错误而非设置 error 属性。若设为 true 或 suspense 为 true，所有错误都将抛出至错误边界。若设为 false 且 suspense 为 false，错误将作为状态返回。若设为函数，该函数将接收错误和查询，并应返回一个布尔值，指示是否应在错误边界中显示错误（true）或作为状态返回错误（false）。 |
queryClient？
使用此选项可指定自定义的 QueryClient。否则，将使用离当前组件最近的上下文中的 QueryClient。
返回值
UseInfiniteQueryResult<TData, TError>
与 useQuery 的返回属性相同，并额外包含 fetchNextPage、fetchPreviousPage、hasNextPage、hasPreviousPage、isFetchingNextPage 和 isFetchingPreviousPage。只要 select 未将 TData 修改为偏离其默认 InfiniteData<TQueryFnData> 结构，还会额外添加 data.pages 和 data.pageParams。
返回属性
| 属性 | 类型 | 描述 |
|---|---|---|
data |
TData | undefined |
查询最后一次成功解析的数据。 |
dataUpdatedAt |
number |
查询最近一次返回 status 状态为 "success" 的时间戳。 |
error |
TError | null |
查询的错误对象（如果抛出了错误）。— 默认为 null。 |
errorUpdateCount |
number |
所有错误的总数。 |
errorUpdatedAt |
number |
查询最近一次返回 status 状态为 "error" 的时间戳。 |
failureCount |
number |
查询失败次数。— 每次查询失败时递增。— 查询成功时重置为 0。 |
failureReason |
TError | null |
查询重试失败的原因。— 查询成功时重置为 null。 |
fetchNextPage |
(options?: FetchNextPageOptions) => Promise<InfiniteQueryObserverResult<TData, TError>> |
此函数允许你拉取下一页结果。 |
fetchPreviousPage |
(options?: FetchPreviousPageOptions) => Promise<InfiniteQueryObserverResult<TData, TError>> |
此函数允许你拉取上一页结果。 |
fetchStatus |
"fetching" | "paused" | "idle" |
查询的拉取状态。— fetching：当 queryFn 正在执行时为 true，包括初始 pending 和后台重新拉取。— paused：查询本应拉取，但已被 paused。— idle：查询未处于拉取中。— 更多信息请参阅 Network Mode。 |
hasNextPage |
boolean |
若存在下一页待拉取（通过 getNextPageParam 选项判定），则为 true。 |
hasPreviousPage |
boolean |
若存在上一页待拉取（通过 getPreviousPageParam 选项判定），则为 true。 |
isEnabled |
boolean |
若该观察者已启用，则为 true；否则为 false。 |
isError |
boolean |
基于 status 变量派生的布尔值，仅作便利性提供。— 若查询尝试导致错误，则为 true。 |
isFetched |
boolean |
若查询已完成拉取，则为 true。 |
isFetchedAfterMount |
boolean |
若查询在组件挂载后完成拉取，则为 true。— 此属性可用于避免显示任何先前缓存的数据。 |
isFetching |
boolean |
基于 fetchStatus 变量派生的布尔值，仅作便利性提供。— 当 queryFn 正在执行时为 true，包括初始 pending 和后台重新拉取。 |
isFetchingNextPage |
boolean |
在使用 fetchNextPage 拉取下一页时为 true。 |
isFetchingPreviousPage |
boolean |
在使用 fetchPreviousPage 拉取上一页时为 true。 |
isFetchNextPageError |
boolean |
若拉取下一页时查询失败，则为 true。 |
isFetchPreviousPageError |
boolean |
若拉取上一页时查询失败，则为 true。 |
isInitialLoading |
boolean |
已弃用 isInitialLoading 已被 isLoading 取代，将在下一个主版本中移除。 |
isLoading |
boolean |
当查询首次拉取正在进行中时为 true。— 与 isFetching && isPending 相同。 |
isLoadingError |
boolean |
若查询首次拉取失败，则为 true。 |
isPaused |
boolean |
基于 fetchStatus 变量派生的布尔值，仅作便利性提供。— 查询本应拉取，但已被 paused。 |
isPending |
boolean |
若尚无缓存数据且尚未完成任何查询尝试，则为 pending。 |
isPlaceholderData |
boolean |
若当前显示的数据为占位数据，则为 true。 |
isRefetchError |
boolean |
若查询在重新拉取时失败，则为 true。 |
isRefetching |
boolean |
当后台重新拉取正在进行中时为 true，不包括 初始 pending。— 与 isFetching && !isPending 相同。 |
isStale |
boolean |
若缓存中的数据已被使失效，或数据比给定的 staleTime 更旧，则为 true。 |
isSuccess |
boolean |
基于 status 变量派生的布尔值，仅作便利性提供。— 若查询已收到无错误响应并已准备好显示其数据，则为 true。 |
refetch |
(options?: RefetchOptions) => Promise<QueryObserverResult<TData, TError>> |
用于手动重新拉取查询的函数。 |
status |
"error" | "pending" | "success" |
查询的状态。— 可能为：— pending：若尚无缓存数据且尚未完成任何查询尝试。— error：若查询尝试导致错误。— success：若查询已收到无错误响应并已准备好显示其数据。 |