TanStack Table PaginationState 详解:pageIndex 与 pageSize 的底层语义与实战配置

发布时间:2026/11/16 17:44:26

TanStack Table PaginationState 详解:pageIndex 与 pageSize 的底层语义与实战配置 TanStack Table PaginationState 详解pageIndex 与 pageSize 的底层语义与实战配置【免费下载链接】table Headless UI for building powerful tables datagrids for TS/JS - React-Table, Vue-Table, Solid-Table, Svelte-Table项目地址: https://gitcode.com/gh_mirrors/ta/tablePaginationState是 TanStack Table本仓库gh_mirrors/ta/table的 monorepo 核心packages/table-core中行分页功能row pagination的状态契约。它由pageIndex当前页码从 0 开始与pageSize每页行数两个字段构成是全库所有分页 API、getPaginatedRowModel行模型切片以及手动/服务端分页模式的共同数据基础。读完本文你将掌握PaginationState两个字段的精确语义、pageSize: Infinity的“单页全量”行为、状态在客户端与服务端分页中的流转方式以及围绕它构建的导航、重置、受控状态等完整 API 用法。接口定义与字段语义PaginationState在 rowPaginationFeature.types.ts 中定义只有两个必填字段export interface PaginationState { pageIndex: number /** * The number of rows per page. Set to Infinity to place all rows on a * single page. */ pageSize: number }pageIndex从 0 开始的当前页码pageIndex表示当前展示的页码从 0 开始计数。这意味着 UI 上通常展示的“第 1 页”对应pageIndex: 0而示例中Page {table.state.pagination.pageIndex 1} of {table.getPageCount()}的渲染方式正是对这种 0 基语义的显式换算见 examples/react/pagination/src/main.tsx。该字段直接影响分页切片计算。在 createPaginatedRowModel.ts 中分页行模型通过pageSize * pageIndex计算起始行、pageStart pageSize计算结束行const { pageSize, pageIndex } pagination ?? getDefaultPaginationState() let paginatedRows rows if (pageSize ! Infinity || pageIndex ! 0) { const pageStart pageSize * pageIndex const pageEnd pageStart pageSize paginatedRows rows.slice(pageStart, pageEnd) }pageSize每页行数pageSize决定每页展示的行数。它有两条重要规则最小值为 1setPageSize内部会执行Math.max(1, ...)钳制防止出现 0 或负数的非法每页行数见 rowPaginationFeature.utils.ts。Infinity表示全部行放在单页这是接口注释明确声明的特殊用法。当pageSize为Infinity时分页切片逻辑整体被跳过见上面createPaginatedRowModel的if分支等价于“不分页一次展示所有行”。从源码看Infinity不仅在切片阶段被特殊处理在页数计算中同样生效table_getPageCount遇到pageSize Infinity且行数有限时直接返回1见 rowPaginationFeature.utils.tsif (pageSize Infinity Number.isFinite(rowCount) rowCount 0) { return 1 } return Math.ceil(rowCount / pageSize)默认状态与初始值PaginationState的默认值由getDefaultPaginationState()提供pageIndex: 0、pageSize: 10见 rowPaginationFeature.utils.ts。这两个默认常量被resetPagination、resetPageIndex、resetPageSize等重置 API 在传入defaultState: true时复用。rowPaginationFeature在初始化时通过getInitialState合并默认值与用户传入的initialState.paginationgetInitialState: (initialState) { return { ...initialState, pagination: { ...getDefaultPaginationState(), ...initialState.pagination, }, } }也就是说你可以通过initialState: { pagination: { pageIndex: 1, pageSize: 20 } }指定表格启动时的页码与每页行数未指定的字段自动回落到默认值。示例代码中该用法的注释形式为// initialState: { pagination: { pageIndex: 1, pageSize: 20 } }, // set the initial page once见 examples/react/pagination/src/main.tsx。分页状态的管理方式PaginationState作为TableState中pagination切片的核心类型支持三种主流管理模式示例代码中对三者均有注释演示见 examples/react/pagination/src/main.tsx1. 内部自动状态默认不显式传入state或atoms表格内部自行持有pagination状态。rowPaginationFeature的默认选项会通过makeStateUpdater(pagination, table)生成onPaginationChange见 rowPaginationFeature.ts导航 API 调用时自动更新内部状态。2. 受控状态classic controlled state显式传入state: { pagination }并搭配onPaginationChange: setPagination回调将新状态写回外部。这种模式适合把分页状态与路由参数、全局 store 同步。3. 外部原子external atoms推荐通过atoms: { pagination: paginationAtom }让外部原子持有该状态切片。类型定义中明确指出“external atoms can own the slice without this callback”见 rowPaginationFeature.types.ts即使用外部原子时无需onPaginationChange状态写入直接作用在原子实例上。围绕 PaginationState 构建的表格 APIPaginationState是分页功能的“数据面”围绕它Table_RowPagination接口提供了一整套“行为面” API见 rowPaginationFeature.types.ts全部由rowPaginationFeature在constructTableAPIs中注册见 rowPaginationFeature.ts状态读取与页数解析table.getPageCount()解析当前总页数。优先级为options.pageCount手动分页时显式提供 由rowCount / pageSize计算且对pageSize Infinity返回 1见 rowPaginationFeature.utils.ts。table.getRowCount()解析分页所用总行数。options.rowCount优先否则取getPrePaginatedRowModel().rows.length即过滤、分组、排序、展开之后、分页切片之前的行数见 rowPaginationFeature.utils.ts。table.getPageOptions()返回零基页码数组如[0, 1, ..., pageCount - 1]未知或空页数时返回空数组见 rowPaginationFeature.utils.ts。导航能力检测table.getCanPreviousPage()pageIndex 0时返回true见 rowPaginationFeature.utils.ts。table.getCanNextPage()pageCount -1未知页数时返回truepageCount 0时返回false否则判断pageIndex pageCount - 1见 rowPaginationFeature.utils.ts。table.getCanLastPage()仅当页数为有限值且pageIndex pageCount - 1时返回true见 rowPaginationFeature.utils.ts。翻页与跳页table.firstPage()/table.previousPage()/table.nextPage()/table.lastPage()分别跳转到第一页、上一页、下一页、最后一页。previousPage与nextPage内部都委托给table_setPageIndex的 updater 形式old - 1/old 1保证状态所有权与 updater 语义一致见 rowPaginationFeature.utils.ts。table.setPageIndex(updater)直接更新pageIndex支持值或函数式 updater并按已知页数钳制在[0, pageCount - 1]之间当pageCount为undefined或-1时不限上限见 rowPaginationFeature.utils.ts。table.setPageSize(updater)更新pageSize最小值钳制为 1同时保持当前顶部行可见——重算pageIndex Math.floor(topRowIndex / pageSize)从Infinity切回有限值时顶行索引归零见 rowPaginationFeature.utils.ts。这一设计在测试中也有覆盖例如从pageSize: Infinity切到10时得到{ pageIndex: 0, pageSize: 10 }见 rowPaginationFeature.utils.test.ts。table.setPagination(updater)以整个PaginationState为粒度的更新入口接受完整对象或函数式 updater见 rowPaginationFeature.utils.ts。重置table.resetPagination(defaultState?)无参时恢复initialState.pagination否则恢复{ pageIndex: 0, pageSize: 10 }见 rowPaginationFeature.utils.ts。table.resetPageIndex(defaultState?)/table.resetPageSize(defaultState?)分别只重置单个字段同样支持“优先initialState、传true用默认值”的两段式语义见 rowPaginationFeature.utils.ts。手动分页服务端分页模式下的字段配合PaginationState不关心数据来自客户端还是服务端它只是纯粹的状态载体。当启用服务端分页时通过manualPagination: true关闭客户端自动切片表格期待传入的数据本身已经是分页后的结果此时需要配合以下选项manualPagination: boolean启用手动分页getPaginatedRowModel不再对行做切片类型注释见 rowPaginationFeature.types.ts。pageCount: number已知总页数时显式传入不确定时设为-1此时getCanNextPage恒返回true、getPageOptions返回空数组、setPageIndex不钳制上限见 rowPaginationFeature.types.ts 与对应工具函数实现。rowCount: number已知总行数时传入pageCount会由rowCount / pageSize自动计算见 rowPaginationFeature.types.ts。table_getRowCount对options.rowCount优先取值验证了这一优先级见 rowPaginationFeature.utils.ts。相关测试证实当manualPagination: true且pageCount: 7时页数解析直接采用配置值而非按行数计算见 rowPaginationFeature.utils.test.ts。页码自动重置autoResetPageIndexPaginationState还关联一个重要行为当数据更新、过滤、排序、分组等“影响页码归属”的状态变化发生时autoResetPageIndex默认true且受autoResetAll全局开关与!manualPagination兜底共同控制会将页码重置回首页避免用户停留在已失效的页码上。其实现逻辑为若当前pageIndex已是 0 则直接跳过避免无意义的回调副作用例如服务端分页场景下每次过滤都触发一次多余的onPaginationChange重取数据否则执行resetPageIndex(table, true)见 rowPaginationFeature.utils.ts。关闭自动重置的写法示例代码注释中给出// autoResetPageIndex: false, // keep the current page after page-altering changes; default true // autoResetAll: false, // turn off every features automatic reset, including page index客户端分页的完整接入流程开启客户端分页需要在功能装配阶段同时注册rowPaginationFeature与createPaginatedRowModel()见 examples/react/pagination/src/main.tsxconst features tableFeatures({ rowPaginationFeature, paginatedRowModel: createPaginatedRowModel(), })其中createPaginatedRowModel返回的是基于tableMemo的记忆化行模型工厂其依赖为“分页前行模型 atoms.pagination值 未启用paginateExpandedRows时的展开状态”见 createPaginatedRowModel.ts因此只有分页相关状态真正变化时才会重建切片结果。随后即可在渲染层消费状态与 API// 导航 button onClick{() table.firstPage()} disabled{!table.getCanPreviousPage()}{}/button button onClick{() table.previousPage()} disabled{!table.getCanPreviousPage()}{}/button button onClick{() table.nextPage()} disabled{!table.getCanNextPage()}{}/button button onClick{() table.lastPage()} disabled{!table.getCanLastPage()}{}/button // 页码显示0 基转 1 基 spanPage {(table.state.pagination.pageIndex 1).toLocaleString()} of {table.getPageCount().toLocaleString()}/span // 跳页 input typenumber min1 max{table.getPageCount()} value{table.state.pagination.pageIndex 1} onChange{(e) table.setPageIndex(Number(e.target.value) - 1)} / // 每页行数含“显示全部” select value{table.state.pagination.pageSize} onChange{(e) table.setPageSize(Number(e.target.value))} {[10, 20, 30, 40, 50].map((pageSize) ( option key{pageSize} value{pageSize}Show {pageSize}/option ))} option value{Infinity}Show All/option /select // 行数统计 spanShowing {table.getRowModel().rows.length.toLocaleString()} of {table.getRowCount().toLocaleString()} Rows/span完整的可运行示例见 examples/react/pagination该示例默认生成 1000 行数据并提供“Stress Test (1M rows)”按钮验证pageSize: Infinity单页展示百万行数据时的行为。小结PaginationState虽只有pageIndex与pageSize两个字段却是 TanStack Table 分页体系的“总开关”pageIndex采用 0 基语义驱动slice(pageSize * pageIndex, pageStart pageSize)的切片计算pageSize最小为 1Infinity表示单页全量展示并影响页数解析与setPageSize的顶行保持策略状态可通过内部自持、受控stateonPaginationChange、外部原子atoms三种方式管理配合manualPagination、pageCount、rowCount、autoResetPageIndex等选项同一套状态模型即可覆盖客户端分页与服务端分页两种场景。若需进一步深入可继续阅读 features.md 中关于分页特性在整体插件架构中的定位或直接研读分页功能的核心源码 rowPaginationFeature.ts 及其配套工具与测试文件。【免费下载链接】table Headless UI for building powerful tables datagrids for TS/JS - React-Table, Vue-Table, Solid-Table, Svelte-Table项目地址: https://gitcode.com/gh_mirrors/ta/table创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
延伸阅读

更多相关文章

2026/11/14 17:04:20

PyCharm安装pyserial全攻略:从pip报错到串口联调实战

前阵子做一个小工具,要用HC05蓝牙模块和电脑串口通信,结果在PyCharm里第一步就栽在了装pyserial上。这个库看着简单,网上一搜教程满天飞,可真照着操作下来,各种报错照样能把人绕晕:“pip不是内部或外部命令…

2026/11/14 20:15:16

Pandas进行stack数据堆叠

Pandas 是 Python 数据处理领域中最强大的工具之一,广泛应用于数据分析、数据清理等任务。stack() 是 Pandas 中的一种强大方法,能够将数据从宽格式转换为长格式,有助于重新组织和转换数据的布局,以便进行更有效的分析。通过理解并掌握 Pandas 的 stack 操作,可以显著提高…

2026/11/17 5:33:24

没电工证找不到工作?涿州人社局电工证+考前押题全攻略来了

没电工证找不到工作?涿州人社局电工证+考前押题全攻略来了 你还在为没特种作业证发愁吗?电工证是很多行业入门的硬门槛,尤其是在建筑、电力、设备安装等领域,没有电工证连面试机会都没有。涿州人社局电工证办理流程复杂,很多人一不小心就错过了报名时间…

2026/11/17 5:33:24

电工证考级哪里报名多久拿证 3个关键点别踩坑

电工证考级哪里报名多久拿证 3个关键点别踩坑 怕考不过白交培训费?南阳卧龙区很多初次报考电工证的小伙伴都问过这个问题。其实,电工证考级哪里报名,多久拿证,这些都不是最难的,难的是选错培训机构、准备不充分、考试没通过。今天我就从报名、考试、备…

2026/11/17 5:33:24

弱电电工证题库怎么用才不交培训费还拿电子证书

弱电电工证题库怎么用才不交培训费还拿电子证书 你是不是也担心,花了几千块报了个弱电电工证培训班,结果考试还是不过,白扔钱?别急,咱们今天就聊聊怎么用好【弱电电工证题库】,既不浪费钱,又能顺利拿到电子证书。…

2026/11/17 5:28:24

电工证复审几分级格怎么过 电子证书怎么查

电工证复审几分级格怎么过 电子证书怎么查 之前考的证在外省能不能转过来,这可能是很多电工朋友在复审时最担心的问题。特别是现在越来越多的证书变成电子证书,大家也更关注这些证件在不同地区是否通用。其实,只要符合国家统一标准,电工证在省内或者跨省…

2026/11/16 7:29:52

电工证考试口诉怎么准备值不值得考

电工证考试口诉怎么准备值不值得考 实操考试心里没底怕挂科,这是大多数准备考电工证的人心里最真实的感受。尤其是面对【电工证考试口诉】环节,很多人不知道该怎么准备,甚至担心自己说不好就被淘汰。其实,只要掌握方法, 值不值得考…

2026/11/16 5:30:20

桑植县考电工证千万别踩坑!报名全流程教你避坑

桑植县考电工证千万别踩坑!报名全流程教你避坑 你是不是也遇到过这种情况:想考个电工证,但不知道从哪儿下手,怕被中介坑,怕花冤枉钱,更怕考了证还不能用?别急,这正是你该看这篇文章的原因。在桑植县考电工证,确实有很多人被坑过,但只要你知道流程、…

2026/11/17 0:02:41

电工证操作和资格证有效期多久?真实经历告诉你怎么复审延期

电工证操作和资格证有效期多久?真实经历告诉你怎么复审延期 证书过期了不知道怎么复审延期,这种情况在电工圈里太常见了。我有个同事,去年刚把低压电工证给弄丢了,直到单位查岗才发现证书已经过期,差点被停工处理。今天就用我真实经历给你讲讲电工证操作…

2026/11/17 0:02:41

机修需不需要电工证 在哪考最靠谱 这些细节必须知道

机修需不需要电工证 在哪考最靠谱 这些细节必须知道 之前考的证在外省能不能转过来?这个问题几乎每个特种作业从业者都问过。特别是像你这样,之前在外省考了证,现在想在本地扎根,或者想换证、换岗的机修人员,最关心的就是【机修需不需要电工证】和【在…

2026/11/17 0:02:41

工地太忙根本没时间复习考试?真实经历告诉你电工证年检步骤是什么

工地太忙根本没时间复习考试?真实经历告诉你电工证年检步骤是什么 工地太忙根本没时间复习考试,我理解你。作为一名刚从焦作工程类院校毕业的学生,我也经历过这种困扰。电工证年检步骤是什么,听起来简单,但实际操作中,很多人因为流程不清楚、资料准备不…

2026/11/17 0:49:41

面向复杂光照与角度的宠物面部识别鲁棒性增强策略

在智慧养宠时代,基于视觉的宠物身份识别技术正逐步从实验室走向家庭应用。然而,与配合度高的人类不同,宠物是典型的“非合作生物识别对象”——它们不会主动配合摄像头调整姿态,更无法控制光照环境。实际应用中,我们常…

2026/11/16 3:17:47

SSM电子书店源码全解析:结构、原理、部署与排错实战

/* MD / 富文本中的 .toc(含博客园搬家等嵌套结构);.toc-box 在侧栏,不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p(:empty 仍占 20px),一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

还想了解更多?直接咨询顾问

免费诊断 + 免费方案 + 透明报价。

全国咨询热线400-8866-253
免费获取方案
☎咨询二维码 ☎ ↑