Solid Query 无限查询(Infinite Queries)实战指南:用 useInfiniteQuery 实现游标/页码分页与无限滚动

原创2026-09-08 09:47:551,700 阅读
文章标签:前端缓存状态管理

Solid Query 无限查询(Infinite Queries)实战指南:用 useInfiniteQuery 实现游标/页码分页与无限滚动

Solid Query 的无限查询(Infinite Queries)通过 useInfiniteQuery 以“页(page)”为单位累积数据,是构建无限滚动列表、下拉加载、聊天气泡历史等场景的标准方案。本文基于 docs/framework/solid/guides/infinite-queries.md 的示例逐步展开,并结合本仓库 packages/solid-query、packages/query-core 的源码与测试用例,讲透 useInfiniteQuery 的数据结构、页面参数计算、加载状态机以及 maxPages 等边界控制手段。读完你可以独立完成一个带“加载更多”、无限滚动、反向历史加载、上限分页等能力的 SolidJS 数据加载组件。

本文示例文档位于 docs/framework/solid/guides/infinite-queries.md,其概念性说明可对照 React 框架的同一主题文档 docs/framework/react/guides/infinite-queries.md 阅读(两者共享同一套底层 @tanstack/query-core 实现)。

无限查询是什么:一次配置,跨请求累积数据

普通 useQuery 每次查询只保存一份响应数据,而无限查询把“同一个列表的多次分页请求结果”累积在一个结构化数据容器里,便于后续所有已加载页面统一展示与失效刷新。

这个容器类型定义在 packages/query-core/src/types.ts:

export interface InfiniteData<TData, TPageParam = unknown> {
  pages: Array<TData>        // 每次 queryFn 返回的一“页”数据,按加载顺序存放
  pageParams: Array<TPageParam> // 与 pages 一一对应,记录每页对应的 pageParam
}

也就是说,useInfiniteQuery 的 data.pages 保存页面数组,data.pageParams 保存取回这些页面所用的参数。后续代码里所有“叠加新页、判断是否还有下一页”的逻辑都不需要你在组件里手动维护。

无限查询区别于普通查询的另外两个关键定义在 packages/query-core/src/types.ts:

  • initialPageParam: TPageParam:必填,第一次请求使用的页面参数(如 0 或某条游标);
  • getNextPageParam: (lastPage, allPages, lastPageParam, allPageParams) => TPageParam | undefined | null:必填,根据已加载的最后一页计算出“下一页参数”,返回 undefined/null 表示没有更多页;
  • getPreviousPageParam:可选,对称地用于反向加载时计算“上一页参数”。

在 SolidJS 环境中调用时,注意 options 需要以**响应式函数(accessor)**的形式传入,这正是 Solid Query 钩子约定俗成的用法(详见下节)。

一个最小可运行实现:Projects 列表 + Load More

下面是最基础的完整示例,来自关联文档的 Example。它包含加载中、出错、成功三个分支,以及一个根据 hasNextPage 启停的“Load More”按钮:

import { Switch, Match, For, Show } from 'solid-js'
import { useInfiniteQuery } from '@tanstack/solid-query'

function Projects() {
  const fetchProjects = async ({ pageParam }) => {
    const res = await fetch('/api/projects?cursor=' + pageParam)
    return res.json()
  }

  const projectsQuery = useInfiniteQuery(() => ({
    queryKey: ['projects'],
    queryFn: fetchProjects,
    initialPageParam: 0,
    getNextPageParam: (lastPage, pages) => lastPage.nextCursor,
  }))

  return (
    <Switch>
      <Match when={projectsQuery.isPending}>
        <p>Loading...</p>
      </Match>
      <Match when={projectsQuery.isError}>
        <p>Error: {projectsQuery.error.message}</p>
      </Match>
      <Match when={projectsQuery.isSuccess}>
        <For each={projectsQuery.data.pages}>
          {(group) => (
            <For each={group.data}>{(project) => <p>{project.name}</p>}</For>
          )}
        </For>
        <div>
          <button
            onClick={() => projectsQuery.fetchNextPage()}
            disabled={!projectsQuery.hasNextPage || projectsQuery.isFetching}
          >
            {projectsQuery.isFetchingNextPage
              ? 'Loading more...'
              : projectsQuery.hasNextPage
                ? 'Load More'
                : 'Nothing more to load'}
          </button>
        </div>
        <Show
          when={projectsQuery.isFetching && !projectsQuery.isFetchingNextPage}
        >
          <div>Fetching...</div>
        </Show>
      </Match>
    </Switch>
  )
}

理解这段示例需要抓住三个要点:

  1. queryFn 的入参:queryFn 会收到一个上下文对象,其中 pageParam 是当前页要用的参数(第一次取 initialPageParam,之后取 getNextPageParam 的返回值)。这里接口设计为 ?cursor=0 的游标翻页,服务端响应里带 nextCursor,因此示例页里项目对象的 name 字段通过 group.data 遍历。
  2. 渲染结构是两层 For:外层遍历 data.pages(每组一页,即一次 queryFn 的返回),内层遍历每页里的列表项。这样你既可以用 <For> 分页渲染,也可以对 pages 做 flatMap 后再渲染单层列表。
  3. 按钮状态由返回值驱动:fetchNextPage() 手动触发下一页加载;hasNextPage 表示是否还有下一页(由 getNextPageParam 是否返回非 undefined 决定);isFetchingNextPage 表示当前是否正在加载下一页;按钮禁用条件是 !hasNextPage || isFetching,避免重复触发。

其中用到的这些状态字段并非 Solid Query 特有,而是由底层 InfiniteQueryObserver 统一产出(见 packages/query-core/src/infiniteQueryObserver.ts),我们会在下文逐一拆解。

必须掌握的返回状态:字段表与判别逻辑

从 useInfiniteQuery 的返回对象可以拿到一组与“页”强相关的字段。对照 packages/solid-query/src/tests/useInfiniteQuery.test.tsx 中记录的两个快照状态可以确认它们的真实取值:

字段 含义 判定/来源
data.pages / data.pageParams 已加载页面数组 / 对应参数数组 缓存中的 InfiniteData
fetchNextPage() / fetchPreviousPage() 手动加载下一页 / 上一页 由 observer 绑定并调用 queryFn
hasNextPage / hasPreviousPage 是否还有下一页 / 上一页 由 getNextPageParam/getPreviousPageParam 的返回值是否为非空推导
isFetchingNextPage / isFetchingPreviousPage 是否正在加载下/上一页 局部加载标识
isFetchNextPageError / isFetchPreviousPageError 最近一次加载下一页是否报错 状态机自动置位
isPending / isError / isSuccess 通用查询状态 与 useQuery 一致
isFetching 是否处于任何抓取中(含翻页) 用于区分后台刷新与翻页加载

hasNextPage 的推导逻辑位于 packages/query-core/src/infiniteQueryBehavior.ts:只要用当前数据调用 getNextPageParam 得到的值不是 undefined/null,就认为存在下一页;hasPreviousPage 额外要求配置了 getPreviousPageParam。

无限查询在失败处理上与普通查询保持一致:“加载更多”某一页失败不会让整条查询进入 error 状态。测试 useInfiniteQuery.test.tsx 中有对应用例验证“should not throw when fetchNextPage returns an error”。所以你的 UI 通常只需关心 isPending/isError 做首屏分支,翻页失败则由 isFetchNextPageError 或 queryFn 内自行处理即可。

首屏“加载中”与渲染层:基于状态做分支

无限查询同样遵循 pending → success / error 的状态迁移,因此文档主示例使用 SolidJS 的 <Switch>/<Match> 对三种状态做互斥分支,而不是叠加多个 if:

  • isPending:首屏尚未有数据,渲染骨架或 Loading...;
  • isError:渲染 projectsQuery.error.message;
  • isSuccess:此时 data 一定存在,可以放心渲染双层 <For>,并在底部放“加载更多”按钮。

一个值得注意的细节是示例末尾的 <Show when={isFetching && !isFetchingNextPage}>:它渲染“Fetching...”指示器,表示发生了不带翻页方向的普通抓取(比如窗口重新聚焦触发 refetch、queryKey 变化后重新请求等),以此与“正在加载下一页”区分开,避免用户同时看到两个互相矛盾的加载提示。

queryFn 的上下文:pageParam 之外还有什么

示例中 fetchProjects = async ({ pageParam }) => ... 只是解构了 pageParam。实际上每抓取一页时,query-core 在 infiniteQueryBehavior.ts 中构造了完整的函数上下文:

const queryFnContext = {
  client,                       // 当前 QueryClient
  queryKey,                     // 当前查询的 key
  pageParam: param,             // 本次页面参数
  direction: previous ? 'backward' : 'forward', // 加载方向
  meta,                         // 查询配置中的 meta
  signal,                       // AbortSignal,可配合 fetch 取消
}

所以当你的分页接口还需要“方向”信息(例如某些聊天 API 区分向前/向后拉取)时,可以直接在 queryFn 里读 direction;需要做请求取消时则把 signal 透传给 fetch。

无限滚动:不必“加载更多”按钮

当列表呈现在可滚动容器中,往往希望在滚动到底部时自动抓取下一页。文档的 Example1 展示了把 fetchNextPage 交给滚动回调的写法:

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

调用前同时检查 hasNextPage 与 isFetching 是防抖的关键:前者避免在“没有更多数据”时反复请求,后者避免在上一页尚未返回时并发叠加载。这里的 <List onEndReached> 是泛化的滚动组件接口,对应到你的实际库(如虚拟滚动、自实现 scroll 监听)就是同一套守卫逻辑。

反向加载:历史记录/消息列表场景

如果你要构建的是“往下翻历史”的界面(比如聊天记录默认展示最新一屏,向上拉取更早内容),就需要同时配置两个函数。文档的 Example3:

useInfiniteQuery(() => ({
  queryKey: ['projects'],
  queryFn: fetchProjects,
  initialPageParam: 0,
  getNextPageParam: (lastPage, pages) => lastPage.nextCursor,
  getPreviousPageParam: (firstPage, pages) => firstPage.prevCursor,
}))

getPreviousPageParam 的入参是第一页与全部页面,返回“向历史方向再取一页”所需的参数。加载时调用 fetchPreviousPage();hasPreviousPage 同样由该函数是否返回非空值决定。底层在 infiniteQueryBehavior.ts 中根据 direction === 'backward' 选择 getPreviousPageParam,并通过 addToStart 把新页追加到 pages 数组的头部,保证 data.pages[0] 始终是最早加载的那一页。

select 数据变换:倒序展示页面

页面数组总是“先加载的在前面”,但历史记录界面通常要把最新一页显示在最底部。此时不需要手动重排存储,只需要用 select 对展示层数据做变换。文档的 Example4:

useInfiniteQuery(() => ({
  queryKey: ['projects'],
  queryFn: fetchProjects,
  initialPageParam: 0,
  getNextPageParam: (lastPage, pages) => lastPage.nextCursor,
  getPreviousPageParam: (firstPage, pages) => firstPage.prevCursor,
  select: (data) => ({
    pages: [...data.pages].reverse(),
    pageParams: [...data.pageParams].reverse(),
  }),
}))

注意两点:

  • pages 与 pageParams 必须同时反转,保持二者的一一对应关系不被破坏;
  • select 会影响 data 的类型与内容,因此示例用 (data) => ({ pages: ..., pageParams: ... }) 显式构造新对象(这里使用了新数组拷贝而不是原地 reverse(),符合缓存数据不可变的原则)。

maxPages:给无限增长的数据加上限

无限查询会把每页数据都留在内存里,用户不停滚动时 pages 会无限膨胀。maxPages 选项用来限制缓存中保留的页面数量,这在某些框架(如 React Native 等长列表场景)中尤为重要。文档的 Example8:

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

maxPages 字段定义在 packages/query-core/src/types.ts(注释为 “Maximum number of pages to store in the data of an infinite query”)。真正执行裁剪逻辑在 infiniteQueryBehavior.ts:向后加载时用 addToEnd(data.pages, page, maxPages),向前加载时用 addToStart(..., maxPages)——保留的总是“最靠近当前加载方向”的最近若干页,从而把旧页挤出缓存。

如果 select 里做了页面反转,请确认反转后的展示顺序仍符合直觉:maxPages 裁剪发生在缓存层(行为函数内部),而 select 作用于最终读取的数据。

数值页码分页:用 lastPageParam 而不是解析响应

游标分页依赖服务端回传的游标字段;如果你的接口是传统的页码分页,无需依赖响应内容,直接基于“上一页参数”做算术即可。文档的 Example9 展示了如何在返回 undefined 时优雅终止:

return useInfiniteQuery(() => ({
  queryKey: ['projects'],
  queryFn: fetchProjects,
  initialPageParam: 0,
  getNextPageParam: (lastPage, allPages, lastPageParam) => {
    if (lastPage.length === 0) {
      return undefined
    }
    return lastPageParam + 1
  },
  getPreviousPageParam: (firstPage, allPages, firstPageParam) => {
    if (firstPageParam <= 1) {
      return undefined
    }
    return firstPageParam - 1
  },
}))

这里的核心技巧在于:

  • 页面参数函数签名是 (lastPage, allPages, lastPageParam, allPageParams)(getNextPageParam)与 (firstPage, allPages, firstPageParam, allPageParams)(getPreviousPageParam),类型见 packages/query-core/src/types.ts;
  • 空页(lastPage.length === 0)或越界(firstPageParam <= 1)时返回 undefined,机制上等价于告诉运行时“没有更多页”;
  • 加载流程在 infiniteQueryBehavior.ts 中循环执行“取当前参数 → 抓页 → 追加”直到参数耗尽或达到目标页数,所以返回 undefined 会立刻终止循环。

Solid 特性:为什么 useInfiniteQuery 接受函数

在 SolidJS 中,所有钩子都应能响应信号变化。useInfiniteQuery 的签名因此设计为接收一个返回配置对象的函数(accessor),内部实现见 packages/solid-query/src/useInfiniteQuery.ts:

return useBaseQuery(
  createMemo(() => options()),
  InfiniteQueryObserver as typeof QueryObserver,
  queryClient,
) as UseInfiniteQueryResult<TData, TError>

也就是说,传入的 options 函数被 createMemo 包装——当函数内部读取的信号(例如查询条件、分页大小)变化时,钩子会以响应式方式重建配置并驱动底层 InfiniteQueryObserver 重新求值。这就是文档所有示例都写作 useInfiniteQuery(() => ({...})) 的原因:不要在回调外层直接求值非纯常量。若想复用一套类型安全的 options,仓库还提供了 infiniteQueryOptions() 辅助函数(见 packages/solid-query/src/infiniteQueryOptions.ts),它能在不调用钩子时让查询键携带精确的推断类型,便于抽离成独立模块。

在渲染与类型层面,useInfiniteQuery 还会依据是否提供 initialData 自动推导 data 是否为可空类型(DefinedInitialDataInfiniteOptions / UndefinedInitialDataInfiniteOptions 两个重载,见 useInfiniteQuery.ts):提供 initialData 时 data 的类型不会包含 undefined,模板里可以直接访问。

底层原理回顾:一次“加载更多”发生了什么

综合以上源码证据,一次 fetchNextPage() 的完整链路可以概括为:

  1. 组件调用 projectsQuery.fetchNextPage();
  2. InfiniteQueryObserver 把本次抓取标记为带方向的 fetchMore(方向 forward),触发查询重新执行;
  3. infiniteQueryBehavior.ts 检测到方向后,用 getNextPageParam(options, oldData) 从缓存数据推导下一页参数;
  4. 参数为 null 且已有页面时直接返回旧数据(L50-L52),否则调用 queryFn 抓取该页;
  5. 新页通过 addToEnd(..., maxPages) 拼接到 pages/pageParams,同时受 maxPages 裁剪;
  6. 数据落缓存后 observer 重新产出 data、hasNextPage、isFetchingNextPage 等新值,SolidJS 模板随之自动更新。

正因为“是否还有下一页、下一页参数是什么”完全由 getNextPageParam/getPreviousPageParam 的返回值推导,这两个函数是无限查询唯一需要精确实现的业务逻辑。建议为它们编写纯函数单测,覆盖“末页返回空”“游标耗尽”“页码越界”等终止条件——这与仓库测试 packages/solid-query/src/tests/useInfiniteQuery.test.tsx 里验证状态迁移的方式是一致的,能显著减少翻页类 bug。

常见问题速查

  • 按钮永远显示 “Nothing more to load”:检查服务端响应结构是否与 getNextPageParam 的取值路径一致,以及到达末页时该函数是否正确返回 undefined 而非 0(0 是合法页参数,会被判定为“还有下一页”)。
  • 滚动到底部重复触发请求:fetchNextPage 的调用点必须同时守卫 hasNextPage 与 isFetching。
  • 页面顺序错乱:双向加载时注意 getPreviousPageParam 用的是 firstPage/pageParams[0];配合 select 反转时保持 pages 与 pageParams 同步反转。
  • 内存增长过快:给配置加上 maxPages,让行为层在拼接时自动裁剪旧页。
  • 历史记录默认展示最新:用“最新一页在前”的正向加载 + select 反转,或用“初始页为最新游标 + getPreviousPageParam 反向加载”,两者在展示上等价但数据组织方向不同,按你的接口语义二选一。
登录后查看全文
query