用途
本技能用于指导在 React 应用中基于 TanStack Query 实现分页查询与无限查询。它覆盖两类典型需求：一是普通分页（页码切换时保留上一页数据以避免闪烁），二是无限滚动或“加载更多”式的游标分页。同时涉及 v5 版本中 keepPreviousData 的迁移写法，以及无限查询缓存数据结构的维护。
主要能力
分页与滞后查询
使用 useQuery 时，通过 placeholderData: keepPreviousData 可以在切换到新页码时保留上一页数据，避免界面出现空白或加载态闪烁。示例中 useProjects(page) 以 ['projects', page] 作为 queryKey，并在 queryFn 中返回当前页数据。
构建无限查询
使用 useInfiniteQuery 构建无限查询，需要提供三个关键配置：
- initialPageParam：初始页参数，v5 中为必填项。
- getNextPageParam：根据最后一页数据推导下一页参数。
- queryFn：接收 pageParam 并返回包含下一页游标与数据项的对象。
示例 useFeed 中，queryFn 返回 { nextCursor: pageParam + 1, items: [...] }，getNextPageParam 读取 lastPage.nextCursor。
限制缓存页数
通过 maxPages 可以限制无限查询在缓存中保留的页数，示例中设置为 5，用于约束内存占用。
保持无限数据形状
使用 queryClient.setQueryData 手动写入无限查询缓存时，数据必须保持 { pages: [...], pageParams: [...] } 的结构，否则后续 refetch 会因结构不符而出错。
使用方式
- 分页场景：引入 keepPreviousData 与 useQuery，在 useQuery 配置中设置 placeholderData: keepPreviousData。
- 无限查询场景：引入 useInfiniteQuery，配置 queryKey、queryFn（使用 pageParam）、initialPageParam 与 getNextPageParam。
- 需要限制内存时，在 useInfiniteQuery 中追加 maxPages。
- 手动写入缓存时，使用 setQueryData 并传入包含 pages 与 pageParams 的对象。
常见错误与正确做法
缺少 initialPageParam（严重）
错误写法中 useInfiniteQuery 未提供 initialPageParam，仅提供 getNextPageParam。正确写法必须显式提供 initialPageParam: 0。v5 要求显式的初始页参数，以便 pageParams 能够被序列化和推断。
无限查询请求重叠（高）
错误写法中“加载更多”按钮未做禁用处理，可能触发多次并发 fetchNextPage。正确写法通过 disabled={query.isFetchingNextPage} 禁用按钮。除非显式覆盖，同一时间只应有一个进行中的请求更新无限查询缓存。
pages 结构被破坏（高）
错误写法将数组直接写入缓存：setQueryData(['feed'], [{ id: 1 }])。正确写法应写入 { pages: [[{ id: 1 }]], pageParams: [0] }。无限查询数据必须保留 pages 与 pageParams，refetch 依赖该结构。
适用场景
- React 应用中的列表分页，且希望在翻页时保留上一页内容。
- 无限滚动、下拉加载更多、游标分页等交互。
- 从旧版 keepPreviousData 用法迁移到 v5 写法。
- 需要控制无限查询缓存页数以约束内存。
- 需要手动写入或更新无限查询缓存数据的场景。
限制
资料仅提供 React 框架下的示例与说明，未涉及其他框架的适配方式。关于具体版本号、安装命令、依赖要求、性能基准、收费或平台信息，资料中暂未提供。