useInfiniteQuery
概述
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?: Accessor<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?: Accessor<QueryClient>): UseInfiniteQueryResult<TData, TError>;DefinedInitialDataInfiniteOptions→DefinedUseInfiniteQueryResult:useInfiniteQuery的选项与useQuery完全相同,额外增加了initialPageParam、getNextPageParam、getPreviousPageParam和maxPages。UndefinedInitialDataInfiniteOptions→UseInfiniteQueryResult:useInfiniteQuery的选项与useQuery完全相同,额外增加了initialPageParam、getNextPageParam、getPreviousPageParam和maxPages。
调用签名
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?: Accessor<QueryClient>): DefinedUseInfiniteQueryResult<TData, TError>;定义于:packages/solid-query/src/useInfiniteQuery.ts:68
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?
Accessor<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 之间共享这些选项。
示例
1import { For } from 'solid-js'2import { useInfiniteQuery } from '@tanstack/solid-query'3 4function Projects() {5 // `projectsQuery.data` is never `undefined`, thanks to `initialData` — even if a refetch fails, so the6 // list stays visible alongside the error.7 const projectsQuery = useInfiniteQuery(() => ({8 queryKey: ['projects'],9 queryFn: ({ pageParam }) => fetchProjects(pageParam),10 initialPageParam: 0,11 getNextPageParam: (lastPage) => lastPage.nextId,12 initialData: { pages: [], pageParams: [] },13 }))14 15 return (16 <div>17 {projectsQuery.isError ? <span>Error: {projectsQuery.error.message}</span> : null}18 <ul>19 <For each={projectsQuery.data.pages}>20 {(page) => <For each={page.projects}>{(p) => <li>{p.name}</li>}</For>}21 </For>22 </ul>23 </div>24 )25}调用签名
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?: Accessor<QueryClient>): UseInfiniteQueryResult<TData, TError>;定义于:packages/solid-query/src/useInfiniteQuery.ts:184
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?
Accessor<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 之间共享这些选项。
示例
通过“加载更多”按钮点击获取下一页:
1import { For, Match, Switch } from 'solid-js'2import { useInfiniteQuery } from '@tanstack/solid-query'3 4function Projects() {5 const projectsQuery = useInfiniteQuery(() => ({6 queryKey: ['projects'],7 queryFn: ({ pageParam }) => fetchProjects(pageParam),8 initialPageParam: 0,9 getNextPageParam: (lastPage) => lastPage.nextId,10 }))11 12 return (13 <Switch>14 <Match when={projectsQuery.isPending}>Loading...</Match>15 <Match when={projectsQuery.isError}>Error: {projectsQuery.error.message}</Match>16 <Match when={projectsQuery.isSuccess}>17 <ul>18 <For each={projectsQuery.data.pages}>19 {(page) => <For each={page.projects}>{(p) => <li>{p.name}</li>}</For>}20 </For>21 </ul>22 <button23 onClick={() => projectsQuery.fetchNextPage()}24 disabled={!projectsQuery.hasNextPage || projectsQuery.isFetching}25 >26 {projectsQuery.isFetchingNextPage27 ? 'Loading more...'28 : projectsQuery.hasNextPage29 ? 'Load More'30 : 'Nothing more to load'}31 </button>32 </Match>33 </Switch>34 )35}利用 IntersectionObserver 在列表末尾的哨兵元素上自动滚动获取下一页:
1import { For, Match, Switch, createEffect, onCleanup } from 'solid-js'2import { useInfiniteQuery } from '@tanstack/solid-query'3 4function Projects() {5 const projectsQuery = useInfiniteQuery(() => ({6 queryKey: ['projects'],7 queryFn: ({ pageParam }) => fetchProjects(pageParam),8 initialPageParam: 0,9 getNextPageParam: (lastPage) => lastPage.nextId,10 }))11 12 let sentinelRef: HTMLDivElement | undefined13 14 createEffect(() => {15 if (sentinelRef == null || !projectsQuery.hasNextPage || projectsQuery.isFetching) return16 17 const observer = new IntersectionObserver(([entry]) => {18 if (entry?.isIntersecting) projectsQuery.fetchNextPage()19 })20 observer.observe(sentinelRef)21 22 onCleanup(() => observer.disconnect())23 })24 25 return (26 <Switch>27 <Match when={projectsQuery.isPending}>Loading...</Match>28 <Match when={projectsQuery.isError}>Error: {projectsQuery.error.message}</Match>29 <Match when={projectsQuery.isSuccess}>30 <ul>31 <For each={projectsQuery.data.pages}>32 {(page) => <For each={page.projects}>{(p) => <li>{p.name}</li>}</For>}33 </For>34 </ul>35 <div ref={sentinelRef}>{projectsQuery.isFetchingNextPage ? 'Loading more...' : null}</div>36 </Match>37 </Switch>38 )39}参数
options
UndefinedInitialDataInfiniteOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>
一个返回 UndefinedInitialDataInfiniteOptions 的访问器 —— 你可传给 useInfiniteQuery 的所有内容。
options 属性
基于 InfiniteQueryOptions 构建。参见上方类型说明其变更内容。
queryClient?
Accessor<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:查询未拉取。- 更多信息请参阅 网络模式。 |
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:若查询已收到无错误的响应且可安全显示其数据。 |