本文由 Huifer 撰写
我使用 TanStack Table 管理视图模型,使用 TanStack Query 管理服务端状态生命周期,因为把这两类职责分开后,分页更容易理解和维护。构建表格时,我会先定义请求契约,再连接 URL 状态、查询键和表格状态。本文没有附带生产环境基准测试;文中的示例是实现指导,不代表经过测量的性能结论。
官方参考: TanStack · TanStack Table 分页 · TanStack Query · TanStack Router · Cloudflare Workers · web.dev · MDN
最后更新:2026-10-24 · 变更日志
TanStack Table React Query Pagination:最佳实践
当表格负责展示状态、TanStack Query 负责服务端响应时,TanStack Table React Query 分页的效果最好。对于大多数 SaaS 管理后台表格,请使用服务端分页,将页码和每页大小放入稳定的查询键,并让 API 返回足够的元数据,使表格知道一共有多少页。本指南面向正在决定如何在现有应用中实现分页,或准备选择一个数据层已经支持分页的模板的 React 开发者。如果周边架构也很重要,可以先比较 SaaS 模板和脚手架,再确定实现方案。
TL;DR
- 只有在浏览器确实会加载完整数据集时,才使用客户端分页。
- 当 API、数据库、权限或筛选条件决定可见行时,使用服务端分页。
- 将
pageIndex和pageSize放入查询键,确保导航会发出正确请求。- 如果希望请求期间继续显示上一页,使用
placeholderData: keepPreviousData。- 让 API 返回
rowCount或pageCount,不要在组件中猜测页数。
独立结论: TanStack Table 负责分页状态和行渲染,TanStack Query 负责获取并缓存每一页数据。可靠的模式是共享分页状态、包含该状态的查询键,以及带有明确总行数元数据的 API 响应。
TanStack Table React Query 分页到底是什么
TanStack Table 是无头组件库:它提供表格状态、行模型和分页行为,但不会决定数据如何到达浏览器。TanStack Query 管理异步服务端数据、缓存、重新获取和加载过渡。TanStack Table 分页指南说明了客户端分页与手动服务端分页之间的边界,TanStack Query 概览则解释了服务端状态层的工作方式。
客户端分页与服务端分页
客户端分页意味着浏览器接收所有行,然后在本地切片。服务端分页则是一次请求一页。两种方案都不会天然更快;正确选择取决于数据归属、授权、筛选条件,以及浏览器是否应该接收完整数据集。
| 决策 | 客户端分页 | 服务端分页 |
|---|---|---|
| 数据集 | 已加载到浏览器 | 从 API 或数据库查询 |
| 筛选 | 在本地应用 | 写入请求契约 |
| 权限 | 数据已经暴露 | 返回行之前执行校验 |
| 元数据 | 表格可以统计本地行数 | API 返回 rowCount 或 pageCount |
| 适用场景 | 小型、有界数据集 | SaaS 记录、审计日志、账单数据 |
实现背后的选型决策
真正的选型问题是:一个 starter 是否已经具备类型安全的服务端数据边界、URL 状态,以及支持权限控制的列表端点。模板无法定义你的领域查询,但可以减少路由、加载、身份验证和部署方面的重复连接工作。选择之前,请检查它的查询缓存、导航行为和分页元数据。
当你想比较这些基础能力,而不是把一个表格组件复制到完全无关的技术栈中时,TanStack Ship 模板分类就是相关的产品入口。
先设计分页契约
稳定的契约可以避免大多数 TanStack Table 和 TanStack Query 分页错误。在编写 hook 之前,先定义 pageIndex、pageSize、允许列表中的 sort、序列化后的 filters 和 rowCount。计数必须反映筛选条件和授权范围。
浏览器应发送小型、可序列化的请求。URLSearchParams 提供了标准编码模型,可以参考 MDN URLSearchParams 文档。服务器必须再次校验每个值,因为客户端校验不是授权边界。
类型化响应结构
这个响应结构刻意保持简单:表格需要行和计数,查询层需要可预测的 promise 和错误路径。
// api/orders.ts
export type OrderPage = {
rows: Order[]
rowCount: number
}
export type OrderPageRequest = {
pageIndex: number
pageSize: number
status?: "open" | "paid" | "refunded"
}
export async function fetchOrders(
request: OrderPageRequest,
signal?: AbortSignal,
): Promise<OrderPage> {
const params = new URLSearchParams({
page: String(request.pageIndex + 1),
pageSize: String(request.pageSize),
})
if (request.status) params.set("status", request.status)
const response = await fetch(`/api/orders?${params}`, { signal })
if (!response.ok) throw new Error("Unable to load orders")
return response.json() as Promise<OrderPage>
}
+ 1 会把从 0 开始的表格状态转换为从 1 开始的 API 页码。请明确测试第一页和最后一页。TanStack Query 查询键指南介绍了如何将请求变量作为缓存身份的一部分。
查询键必须包含每个请求变量
如果 status 发生变化但查询键没有变化,组件可能会显示错误筛选条件下的页面。如果 pageSize 发生变化,而查询键只包含 pageIndex,缓存数据可能会在不兼容的请求下被复用。任何会改变返回行的变量都必须纳入查询键。
import {
keepPreviousData,
useQuery,
} from "@tanstack/react-query"
const paginationKey = [
"orders",
{ pageIndex, pageSize, status },
] as const
const ordersQuery = useQuery({
queryKey: paginationKey,
queryFn: ({ signal }) =>
fetchOrders({ pageIndex, pageSize, status }, signal),
placeholderData: keepPreviousData,
})
keepPreviousData 是过渡体验的选择,不是正确性的保障。请显示新页面正在获取的状态,避免用户把上一页误认为当前结果。参见分页查询文档。
将 TanStack Table 连接到查询状态
对于服务端分页,请设置 manualPagination: true,这样表格就不会再次切分响应数据。传入 rowCount,让它能够推导页数。参见手动分页部分。
import {
getCoreRowModel,
useReactTable,
} from "@tanstack/react-table"
const table = useReactTable({
data: ordersQuery.data?.rows ?? [],
columns,
getCoreRowModel: getCoreRowModel(),
manualPagination: true,
rowCount: ordersQuery.data?.rowCount ?? 0,
state: { pagination: { pageIndex, pageSize } },
onPaginationChange: setPagination,
})
关键不变量是:同一份状态必须同时到达 queryKey 和 state.pagination。当需要让其他状态所有者与表格同步时,请参考 TanStack Table 受控状态指南。
筛选条件变化时重置页码
筛选条件可能让当前页失效。如果第 8 页的结果缩小到只有两页,pageIndex 7 就会返回空结果。当筛选条件或排序发生变化时,应将页码重置为 0。
对于需要分享的列表,请将分页和筛选条件存储在路由的搜索参数中。TanStack Router 搜索参数提供了类型化路由模型;避免同时维护互相分叉的 URL 状态和组件状态。
处理加载、错误和空页面
分页不只有“有行”或“没有行”两种状态。请区分初始加载和后台过渡,禁用重复导航,提供重试行为,区分筛选后为空与页码越界,并在变更操作后让受影响的查询失效。
如果要思考写入后如何刷新列表查询,TanStack Query 查询失效指南是合适的参考。除非你有清晰的一致性模型,否则不要手动修补每一页;查询失效通常更容易验证。
具体实现边界
问题: 更改每页大小后,表格显示了重复行。
根因: 旧页面仍然留在查询键中,或者表格继续对服务端分页数据应用客户端行模型。
解决方案: 在查询键中包含 pageSize,设置 manualPagination: true,并在每页大小变化时将 pageIndex 重置为 0。
结果: UI 请求并渲染一个定义明确的服务端页面。这是正确性结果,不是经过测量的性能结论。
问题: 用户可以请求未授权的页面或筛选条件。
根因: 端点信任查询字符串字段,而权限检查只在 React 组件中执行。
解决方案: 校验页码边界,将排序字段限制在允许列表中,并在服务端查询中应用租户或用户范围。当端点运行在带数据库请求的边缘环境时,Cloudflare Workers 文档和 Cloudflare D1 文档可以作为起点。
结果: 浏览器只会收到服务端策略允许的行。仍然需要编写符合具体应用授权规则的测试。
性能与无障碍检查
分页会减少每次请求传输的数据量,但不会自动让表格具备无障碍能力或变得更快。请在具有代表性的数据集和真实网络条件下,测量用户可感知的结果。web.dev Web Vitals介绍了需要关注的以用户为中心的指标,MDN HTTP 概览则解释了 fetch 调用底层的请求与响应行为。
在认为表格已经准备好之前,我会检查以下细节:
- 页码、总页数和加载状态会暴露给辅助技术。
- 上一页和下一页控件会在正确的边界处禁用。
- 页面切换后键盘焦点仍然保留。
- API 会限制
pageSize,拒绝无效排序字段,并返回真实计数。
如果你的数据库是 Supabase,请参考 Supabase 数据库文档了解查询和授权层。如果使用其他数据库,也应遵循同一原则:分页 UI 应反映服务端的实际契约,而不是组件中写死的假设。
我会测量什么,以及不会做出什么承诺
请在自己的环境中测量请求耗时、响应大小、错误率和交互耗时。如果没有受控基准测试,我不会声称有固定比例的提升;索引、序列化、网络距离、缓存状态和渲染成本都会改变结果。
请测试第一页、中间页和最后一页,也要测试空结果、权限受限结果、缓慢响应、失败响应、浏览器前进后退行为,以及带分页参数直接打开的 URL。
哪种模板适合这个用例?
选择模板或 starter 时,应根据周边能力,而不是它是否包含一个表格示例。请检查它的类型化列表查询边界、身份验证和租户范围、查询失效约定、URL 状态以及部署路径。
如果你正在比较实现基础设施,可以使用 SaaS 脚手架选型指南一起评估这些能力。然后浏览 TanStack 模板,寻找路由、数据加载和部署选择与你的产品匹配的模板。真正的决策是:哪一种基础设施能让分页周围最少存在无人负责的边界。
结论:可靠的分页决策
对于 TanStack Table React Query 分页,请让表格负责分页状态和渲染,让 TanStack Query 负责服务端数据,并让 API 返回明确的行数元数据。当筛选条件、权限或数据库所有权参与其中时,使用服务端分页;只有在完整数据集确实有意保存在本地时,才使用客户端分页。
下一步: 根据所需的列表查询能力,对比 SaaS 脚手架选项,然后在实现表格边界之前浏览可用模板。
FAQ:TanStack Table 分页应该采用客户端还是服务端?
当完整数据集已经加载,并且可以安全地暴露给浏览器时,使用客户端分页。当行来自数据库、筛选条件会影响授权,或者数据集应该增量加载时,使用服务端分页。表格配置和 API 契约应明确表达这一选择,避免意外混用两种模式。
FAQ:TanStack Query 应如何缓存分页表格数据?
将所有会改变响应的请求变量放入查询键:页码、每页大小、筛选条件、排序、租户范围以及其他服务端参数。当稳定的过渡体验有帮助时,可以使用 keepPreviousData,但仍要显示获取指示器,让用户知道当前可见行可能代表上一份请求。
FAQ:SaaS 模板是否需要内置 TanStack Table 分页?
不一定。模板的价值在于提供表格周围的边界:类型化数据加载、身份验证、URL 状态、查询失效约定和部署能力。表格组件之后再添加也可以。购买之前,请验证模板的实际架构,选择能够支持你的查询和权限模型,同时不会隐藏重要行为的方案。
相关文章: Tanstack Query V5 Best Practices · Tanstack Query V5 Migration And Best Practices · Tanstack Query V5 Migration And Best Practices 2026
披露与限制
本文是技术指导,不是基准测试、安全审计,也不保证取得特定结果。文中的主张都标明了依据:实现示例属于计算或演示性质,文档参考是根据所链接来源测得,而环境相关的结果在测试前都属于未知。我与此处链接的外部文档项目不存在利益关系。如果你发现错误,请使用变更日志,或通过关于页面联系作者;修正内容应以相关库和运行时文档为准。