无限查询

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

渲染可增量“加载更多”数据到现有数据集上或实现“无限滚动”的列表，也是一种非常常见的 UI 模式。TanStack Query 支持一种适用于此类列表的实用版 useQuery，称为 useInfiniteQuery。

使用 useInfiniteQuery 时，你会注意到以下几点差异：

data 现在是一个包含无限查询数据的对象：
data.pages 数组，包含已拉取的页面
data.pageParams 数组，包含用于拉取各页面的页面参数
现在可使用 fetchNextPage 和 fetchPreviousPage 函数（其中 fetchNextPage 为必需项）
现在可使用（且必需）initialPageParam 选项来指定初始页面参数
getNextPageParam 和 getPreviousPageParam 选项可用于判断是否还有更多数据可加载，以及获取加载所需的信息。该信息将作为额外参数传入查询函数
现在可使用 hasNextPage 布尔值；当 getNextPageParam 返回值不为 null 或 undefined 时，其值为 true
现在可使用 hasPreviousPage 布尔值；当 getPreviousPageParam 返回值不为 null 或 undefined 时，其值为 true
现在可使用 isFetchingNextPage 和 isFetchingPreviousPage 布尔值，以区分后台刷新状态与“加载更多”状态

注意：initialData 或 placeholderData 选项需符合具有 data.pages 和 data.pageParams 属性的对象结构。

示例

假设我们有一个 API，它根据 cursor 索引每次返回 projects 3 条，并附带一个可用于获取下一组项目的游标：

TypeScript

1fetch('/api/projects?cursor=0')2// { data: [...], nextCursor: 3}3fetch('/api/projects?cursor=3')4// { data: [...], nextCursor: 6}5fetch('/api/projects?cursor=6')6// { data: [...], nextCursor: 9}7fetch('/api/projects?cursor=9')8// { data: [...] }

基于此信息，我们可通过以下方式构建“加载更多” UI：

默认等待 useInfiniteQuery 请求第一组数据
在 getNextPageParam 中返回下一次查询所需的信息
调用 fetchNextPage 函数

TypeScript

1import { useInfiniteQuery } from '@tanstack/react-query'2 3function Projects() {4  const fetchProjects = async ({ pageParam }) => {5    const res = await fetch('/api/projects?cursor=' + pageParam)6    return res.json()7  }8 9  const {10    data,11    error,12    fetchNextPage,13    hasNextPage,14    isFetching,15    isFetchingNextPage,16    status,17  } = useInfiniteQuery({18    queryKey: ['projects'],19    queryFn: fetchProjects,20    initialPageParam: 0,21    getNextPageParam: (lastPage, pages) => lastPage.nextCursor,22  })23 24  return status === 'pending' ? (25    <p>Loading...</p>26  ) : status === 'error' ? (27    <p>Error: {error.message}</p>28  ) : (29    <>30      {data.pages.map((group, i) => (31        <React.Fragment key={i}>32          {group.data.map((project) => (33            <p key={project.id}>{project.name}</p>34          ))}35        </React.Fragment>36      ))}37      <div>38        <button39          onClick={() => fetchNextPage()}40          disabled={!hasNextPage || isFetching}41        >42          {isFetchingNextPage43            ? 'Loading more...'44            : hasNextPage45              ? 'Load More'46              : 'Nothing more to load'}47        </button>48      </div>49      <div>{isFetching && !isFetchingNextPage ? 'Fetching...' : null}</div>50    </>51  )52}

必须理解的是，在已有拉取正在进行时调用 fetchNextPage，存在覆盖后台正在进行的数据刷新的风险。当渲染列表并同时触发 fetchNextPage 时，这一情况尤为关键。

请记住，一个 InfiniteQuery 只能存在一次正在进行的拉取。所有页面共享单个缓存条目；若尝试同时发起两次拉取，可能导致数据被覆盖。

如需启用并发拉取，可在 fetchNextPage 中使用 { cancelRefetch: false } 选项（默认值：true）。

为确保查询过程无缝且无冲突，强烈建议验证查询是否处于 isFetching 状态，尤其当用户无法直接控制该调用时。

JavaScript

1<List onEndReached={() => hasNextPage && !isFetching && fetchNextPage()} />

当无限查询需要重新拉取时会发生什么？

当无限查询变为 stale 并需要重新拉取时，各组数据将按顺序从第一组开始 sequentially 拉取。这确保了即使底层数据已被修改，我们也不会使用过期的游标，从而避免重复或跳过记录。如果无限查询的结果曾从 queryCache 中移除，则分页将重置为初始状态，仅请求初始组数据。

如果我想实现双向无限列表怎么办？

可通过使用 getPreviousPageParam、fetchPreviousPage、hasPreviousPage 和 isFetchingPreviousPage 属性与函数来实现双向列表。

TypeScript

1useInfiniteQuery({2  queryKey: ['projects'],3  queryFn: fetchProjects,4  initialPageParam: 0,5  getNextPageParam: (lastPage, pages) => lastPage.nextCursor,6  getPreviousPageParam: (firstPage, pages) => firstPage.prevCursor,7})

如果我想以倒序显示页面怎么办？

有时你可能希望以倒序显示页面。若如此，可使用 select 选项：

TypeScript

1useInfiniteQuery({2  queryKey: ['projects'],3  queryFn: fetchProjects,4  select: (data) => ({5    pages: [...data.pages].reverse(),6    pageParams: [...data.pageParams].reverse(),7  }),8})

如果我想手动更新无限查询怎么办？

手动移除第一页：

TypeScript

1queryClient.setQueryData(['projects'], (data) => ({2  pages: data.pages.slice(1),3  pageParams: data.pageParams.slice(1),4}))

手动从某一页中移除单个值：

TypeScript

1const newPagesArray =2  oldPagesArray?.pages.map((page) =>3    page.filter((val) => val.id !== updatedId),4  ) ?? []5 6queryClient.setQueryData(['projects'], (data) => ({7  pages: newPagesArray,8  pageParams: data.pageParams,9}))

仅保留第一页：

TypeScript

1queryClient.setQueryData(['projects'], (data) => ({2  pages: data.pages.slice(0, 1),3  pageParams: data.pageParams.slice(0, 1),4}))

请务必始终维持 pages 和 pageParams 的相同数据结构！

如果我想限制页面数量怎么办？

在某些场景中，你可能希望限制查询数据中存储的页面数量，以提升性能和用户体验：

当用户可加载大量页面时（内存占用）
当你需要重新拉取包含数十页的无限查询时（网络开销：所有页面将按顺序依次拉取）

解决方案是使用“受限无限查询”（Limited Infinite Query）。这可通过结合使用 maxPages 选项与 getNextPageParam 和 getPreviousPageParam 实现，从而支持按需在两个方向上拉取页面。

在以下示例中，查询数据的 pages 数组仅保留 3 页。若需重新拉取，也仅会按顺序重新拉取这 3 页。

TypeScript

1useInfiniteQuery({2  queryKey: ['projects'],3  queryFn: fetchProjects,4  initialPageParam: 0,5  getNextPageParam: (lastPage, pages) => lastPage.nextCursor,6  getPreviousPageParam: (firstPage, pages) => firstPage.prevCursor,7  maxPages: 3,8})

如果我的 API 不返回游标怎么办？

如果你的 API 不返回游标，可将 pageParam 用作游标。由于 getNextPageParam 和 getPreviousPageParam 同样接收当前页的 pageParam，你可以据此计算出下一页 / 上一页的参数。

TypeScript

1return useInfiniteQuery({2  queryKey: ['projects'],3  queryFn: fetchProjects,4  initialPageParam: 0,5  getNextPageParam: (lastPage, allPages, lastPageParam) => {6    if (lastPage.length === 0) {7      return undefined8    }9    return lastPageParam + 110  },11  getPreviousPageParam: (firstPage, allPages, firstPageParam) => {12    if (firstPageParam <= 1) {13      return undefined14    }15    return firstPageParam - 116  },17})

延伸阅读

如需更深入地了解无限查询在底层的工作原理，请参阅文章无限查询的工作原理。