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），仅供参考
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），仅供参考
