译零 TransZero · TanStack Query 中文文档
主站

useInfiniteQuery

更新于 2026-11-02 Solid 查看英文原文 ↗

概述

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?: 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>;

另请参阅:参数 · 返回值

调用签名

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?: 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 之间共享这些选项。

示例

TypeScript
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}

调用签名

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?: 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 之间共享这些选项。

示例

通过“加载更多”按钮点击获取下一页:

TypeScript
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 在列表末尾的哨兵元素上自动滚动获取下一页:

TypeScript
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:若查询已收到无错误的响应且可安全显示其数据。

本页为 TanStack Query 文档(Solid 版)的非官方中文翻译,原文由上游团队维护,遵循 MIT 许可。 译文如有偏差,以英文原文为准。

译自上游 59d11de