Ant Design Pagination 每页条数切换器showSizeChanger完整实战指南【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/GitHub_Trending/an/ant-design导读在管理后台与数据表格类页面中用户经常需要在一页内查看不同数量的数据条目。Ant Design 的 Pagination 组件通过showSizeChanger支持切换每页显示条目数即pageSize本文将以 components/pagination/demo/changer.md 及其配套示例 changer.tsx 为主线系统讲解该功能的属性配置、事件回调、全局默认值与源码实现原理。读完本文你将能够精确控制条数切换器的选项、回调与禁用状态并能理解其底层与 Select 组件的协作关系。一、示例现象切换 pageSize 发生了什么changer.md 的说明非常聚焦——改变每页显示条目数ChangepageSize。与之对应的完整示例代码位于 changer.tsximport React from react; import type { PaginationProps } from antd; import { Pagination } from antd; const onShowSizeChange: PaginationProps[onShowSizeChange] (current, pageSize) { console.log(current, pageSize); }; const App: React.FC () ( Pagination showSizeChanger onShowSizeChange{onShowSizeChange} defaultCurrent{3} total{500} / br / Pagination showSizeChanger onShowSizeChange{onShowSizeChange} defaultCurrent{3} total{500} disabled / / ); export default App;该示例渲染了两个分页器第一个开启showSizeChanger默认停在第三页defaultCurrent{3}总数据量 500 条total{500}右侧出现一个用于选择每页条数的下拉框用户切换后通过onShowSizeChange打印当前页码与新 pageSize。第二个同样配置但增加了disabled整个分页器包括条数切换下拉框进入禁用态演示大规模数据场景下的只读回显。从 index.en-US.md 的 API 表可知total的默认值是0、defaultPageSize的默认值是10示例中没有显式传入pageSize因此切换器选项在用户操作前实际对应每页 10 条。二、控制条数切换器的四个关键属性要让改变每页条数真正可用需要把下面几个属性组合理解。1. showSizeChanger是否显示切换器类型为boolean | SelectProps从 Pagination.tsx 的定义可见其可同时接收 Select 的全部属性。API 文档标注SelectProps形式自 5.21.0 支持且该属性可通过 ConfigProvider 全局配置 统一设定自 4.21.0 起。showSizeChanger并不是简单的开关其解析逻辑被单独抽到了 useShowSizeChanger.tsif (typeof showSizeChanger boolean) { return [showSizeChanger, {}]; } if (isPlainObject(showSizeChanger)) { return [true, showSizeChanger]; } return [undefined, undefined];传true显示切换器无额外 Select 配置传 Select 属性对象如{ showSearch: false }等价于打开切换器并透传给内部 Select不传返回undefined由后续逻辑回落到 ConfigProvider 的全局配置或最终默认值。2. pageSizeOptions切换器的候选项类型为(string | number)[]默认值是[10, 20, 50, 100]。注意源码中无论传入字符串还是数字都会被转换为数字见 Pagination.tsxconst mergedPageSizeOptions React.useMemo(() { return pageSizeOptions ? pageSizeOptions.mapnumber(Number) : undefined; }, [pageSizeOptions]);因此pageSizeOptions{[10, 20, 50]}与pageSizeOptions{[10, 20, 50]}效果一致。此外如果当前pageSize不在候选列表内切换器展示的值会按选项与当前 pageSize 的字符串匹配来落定见 Pagination.tsx。3. onShowSizeChange切换后的回调function(current, size)在 pageSize 变化时触发。示例中const onShowSizeChange: PaginationProps[onShowSizeChange] (current, pageSize) { console.log(current, pageSize); };current切换发生时所处的页码pageSize新选中的每页条数。值得注意pageSize 变化时onChange(page, pageSize)也会一并触发。这在 components/pagination/tests/index.test.tsx 的测试中被明确验证it(should onChange called when pageSize change, () { ... fireEvent.click(container.querySelectorAll(.ant-select-item-option)[1]); expect(onChange).toHaveBeenCalledWith(1, 20); });该测试断言数据量 500、默认每页 10 条时切换器渲染出4 个选项对应默认[10, 20, 50, 100]选中第二项后onChange收到(1, 20)——页码仍为第 1 页pageSize 变为 20。4. 相关的受控/非受控与边界属性属性类型默认值说明pageSizenumber-受控的每页条数切换器选中后会回调更新defaultPageSizenumber10非受控时的初始每页条数defaultCurrentnumber1初始页码currentnumber-受控页码totalnumber0数据总条数决定总页数与是否可切换totalBoundaryShowSizeChangernumber50当total大于该值时showSizeChanger才生效6.2.0 起totalBoundaryShowSizeChanger是设计上的护栏数据量不足 50 条时默认不展示条数切换器避免无意义的操作示例中total{500}远大于 50因此切换器必然出现。它同样支持 ConfigProvider 全局配置见 Pagination.tsx 对 context 值的合并逻辑。三、源码视角切换器如何变成 SelectPagination 在 Ant Design 中并非纯自研组件它对外包装了rc-component/pagination而条数切换器部分则复用了 antd 的 Select 能力相关装配代码集中在 Pagination.tsx。核心流程如下合并来源分别用useShowSizeChanger解析组件自身属性与 ConfigProvider 的 context 配置再通过空值合并得到最终的mergedShowSizeChanger与合并后的 Select 属性Pagination.tsx。构造切换器渲染函数sizeChangerRender接收rc-pagination传入的{ disabled, size, onSizeChange, options, ... }。若用户通过components.sizeChanger提供了自定义切换组件则优先使用自 6.6.0 支持见 Pagination.tsx否则渲染标准Select。Select 细节切换器 Select 固定开启showSearch、popupMatchSelectWidth{false}并通过getPopupContainer把弹层挂到触发节点父级下Pagination.tsx保证在滚动容器内弹层定位正确onChange中先调用onSizeChange驱动 rc 层翻页状态再透传用户配置的propSizeChangerOnChangePagination.tsx。禁用态贯通disabled会一路传给 Select 与页码按钮这就是示例中第二个disabled分页器整体不可交互的原因相关测试见 index.test.tsx。把showSizeChanger直接写成对象形式如{ showSearch: false }即可精细化控制该 Select对应测试位于 index.test.tsx它验证了传入对象后下拉框搜索框被关闭的行为。四、通过 ConfigProvider 统一管理每页条数交互在大型项目中与其在每个 Pagination 上重复写showSizeChanger、pageSizeOptions不如在 config-provider 中做一次全局声明。源码通过useComponentConfig(pagination)读取全局配置再把showSizeChanger与totalBoundaryShowSizeChanger等字段合并进最终 propsPagination.tsx。例如ConfigProvider componentConfig{{ pagination: { showSizeChanger: true, pageSizeOptions: [10, 20, 30, 50, 100], }, }} App / /ConfigProvider组件自身显式传入的showSizeChanger优先级高于全局配置这保证了局部覆盖能力。五、综合示例完整可复用的可切换条数分页将 changer.tsx 的能力与showTotal、受控pageSize结合可以得到更贴近后台列表的场景import React, { useState } from react; import { Pagination } from antd; const App: React.FC () { const [pageSize, setPageSize] useState(20); return ( Pagination total{500} current{1} pageSize{pageSize} showSizeChanger showQuickJumper showTotal{(total, range) ${range[0]}-${range[1]} of ${total} items} onShowSizeChange{(_, size) setPageSize(size)} / ); }; export default App;这里通过onShowSizeChange更新受控pageSize再配合onChange重新拉取数据即可实现切换条数即刷新列表的标准交互。类似的组合形态还可见 all.tsxshowSizeChanger与showQuickJumper、showTotal同屏展示。六、实战要点与注意事项回调时机修改每页条数时会同时触发onShowSizeChange(current, size)与onChange(page, pageSize)后端请求只需监听onChange一个入口即可避免重复拉数。条数变更后的页码策略切到更大的 pageSize 后页码通常会回落具体以onChange收到的page为准勿自行假设页码不变。默认阈值 50当total 50时即使设置showSizeChanger也可能不显示若业务必须展示可显式设置totalBoundaryShowSizeChanger{0}。尺寸联动pageSizeOptions建议保持升序且包含默认pageSize如列表中已有每页 200 条的偏好可自行扩展候选值。全局统一多页面系统优先通过 ConfigProvider 的componentConfig.pagination统一开启减少重复代码也便于后续统一调整。从 changer.tsx 的演示到 Pagination.tsx、useShowSizeChanger.ts 与 index.test.tsx 的实现佐证可以看出改变每页显示条目数这一看似简单的交互背后是分页状态、Select 复用、全局配置合并与禁用态透传的完整链路。掌握showSizeChanger、pageSizeOptions、onShowSizeChange三者的配合方式即可在真实项目中稳定落地。【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/GitHub_Trending/an/ant-design创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考