Solid Query 无限查询(Infinite Queries)实战指南:用 useInfiniteQuery 实现游标/页码分页与无限滚动
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>
)
}
理解这段示例需要抓住三个要点:
- queryFn 的入参:queryFn 会收到一个上下文对象,其中
pageParam是当前页要用的参数(第一次取initialPageParam,之后取getNextPageParam的返回值)。这里接口设计为?cursor=0的游标翻页,服务端响应里带nextCursor,因此示例页里项目对象的name字段通过group.data遍历。 - 渲染结构是两层 For:外层遍历
data.pages(每组一页,即一次 queryFn 的返回),内层遍历每页里的列表项。这样你既可以用<For>分页渲染,也可以对 pages 做flatMap后再渲染单层列表。 - 按钮状态由返回值驱动:
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() 的完整链路可以概括为:
- 组件调用
projectsQuery.fetchNextPage(); InfiniteQueryObserver把本次抓取标记为带方向的fetchMore(方向forward),触发查询重新执行;- infiniteQueryBehavior.ts 检测到方向后,用
getNextPageParam(options, oldData)从缓存数据推导下一页参数; - 参数为
null且已有页面时直接返回旧数据(L50-L52),否则调用 queryFn 抓取该页; - 新页通过
addToEnd(..., maxPages)拼接到pages/pageParams,同时受maxPages裁剪; - 数据落缓存后 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反向加载”,两者在展示上等价但数据组织方向不同,按你的接口语义二选一。