企业官网建设流程全解析

Ant Design Pagination 分页组件完全指南：从基础用法到源码实现原理

【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/gh_mirrors/antde/ant-design

导读

本文以 ant-design 仓库中 Pagination 分页组件文档 为核心，结合组件源码与全部 9 个官方示例，系统讲解分页组件的使用时机、全部 API 参数、受控与非受控用法、迷你/简洁/跳转/总数展示等实战场景，并深入到rc-pagination的底层实现与 antd 的封装细节，帮助你在长列表数据渲染场景中正确选择、配置与扩展分页方案。

为什么需要分页

当页面需要展示的数据量很大时，一次性加载或渲染全部数据会带来明显的性能开销与糟糕的交互体验。Pagination 采用分页的形式分隔长列表，每次只加载一个页面，用户通过切换页码浏览数据。根据官方文档，分页的适用场景非常明确：

• 当加载/渲染所有数据将花费很多时间时；
• 当用户需要可切换页码来浏览数据时。

这与 表格组件 的分页、列表模式设计文档 中关于大量数据展示的实践一脉相承，是长列表数据展示的标准解决方案。

快速上手：最小可运行示例

最简单的分页只需要传入数据总数即可工作：

<Pagination onChange={onChange} total={50} />

对应到仓库中的 基础示例，默认从第 1 页开始展示：

import { Pagination } from 'antd'; ReactDOM.render( <Pagination defaultCurrent={1} total={50} />, mountNode);

当total较大时（例如 更多分页示例 中的 500 条数据），组件会自动折叠中间页面的编号，用省略号（ellipsis）代替，避免页码条过长：

import { Pagination } from 'antd'; ReactDOM.render( <Pagination defaultCurrent={1} total={500} />, mountNode);

API 参数详解

Pagination 的核心 API 全部定义在文档的 API 表格中。它本质上是 antd 对rc-pagination的一层封装（见 index.jsx），所有参数最终透传给底层组件，同时附加了 antd 自己的Select下拉组件用于切换每页条数。下面逐一讲解每个参数。

页码相关：current 与 defaultCurrent

• defaultCurrent是非受控用法下的初始页码。不传任何页码相关属性时，组件内部默认从第 1 页开始；
• current是受控属性。一旦传入current，页码就完全由外部状态决定，页码的跳转必须通过onChange回调更新状态来完成（详见下文"受控分页"小节）。

数据量相关：total、defaultPageSize 与 pageSize

• total是必传的关键属性，组件依据它与pageSize计算总页数；
• defaultPageSize为非受控方式指定初始每页条数，默认 10 条；
• pageSize为受控属性，用于外部完全控制每页条数，例如与"每页条数选择器"联动。

回调函数：onChange 与 onShowSizeChange

• onChange(page)在用户切换页码时触发，参数为改变后的页码；
• onShowSizeChange(current, size)在每页条数改变时触发，同时接收当前页码与新的每页条数两个参数。二者配合即可在分页变化后重新向后端发起数据请求。

每页条数选择器：showSizeChanger 与 pageSizeOptions

• 开启showSizeChanger后，分页器右侧会出现一个下拉选择器，允许用户调整每页条数；
• 可选项由pageSizeOptions控制，默认提供 10/20/30/40 四个档位。

这里有一个值得注意的源码细节：antd 在封装时专门为小尺寸分页准备了MiniSelect，用size="small"的 Select 替换默认的 Select（见 index.jsx），使选择器与迷你分页的视觉尺寸保持一致。

快捷跳转：showQuickJumper

开启后分页器尾部出现输入框，用户直接输入页码即可快速跳转，适用于数据量大的场景。完整用法见 跳转示例：

import { Pagination } from 'antd'; ReactDOM.render( <Pagination showQuickJumper defaultCurrent={2} total={500} />, mountNode);

尺寸与形态：size、simple 与 showTotal

• size="small"输出迷你分页。在 index.jsx 中可以看到，小尺寸会给className追加mini标记，同时切换为MiniSelect选择器，样式上由 style/components/pagination.less 中的.ant-pagination.mini规则支撑；
• simple是布尔属性（文档标注类型为 Object，实为"添加即生效"的标志性属性），渲染为只有"上一页/下一页 + 当前页/总页数"的极简形态，适合移动端或空间受限的场景；
• showTotal(total, range)接收数据总数（以及可能的页码范围），用于在分页器左侧展示"共 xx 条"之类的统计信息。

国际化：locale

仓库中 locale/zh_CN.js 与 locale/en_US.js 直接复用rc-pagination/lib/locale下的对应语言包，组件默认注入zh_CN（见 index.jsx）。切换语言只需通过locale属性传入对应语言包即可，见 国际化示例：

import { Pagination } from 'antd'; import enUS from 'antd/lib/pagination/locale/en_US'; ReactDOM.render( <Pagination defaultCurrent={1} total={50} locale={enUS} />, mountNode);

经典实战场景

场景一：受控分页

当页码需要与其他组件（如表格数据、路由参数）保持同步时，应使用受控模式。核心是"外部状态 + onChange 回写"，见 受控示例：

import { Pagination } from 'antd'; let Container = React.createClass({ getInitialState() { return { current: 3 }; }, onChange(page) { console.log(page); this.setState({ current: page }); }, render() { return <Pagination current={this.state.current} onChange={this.onChange} total={50} />; } }); ReactDOM.render( <Container />, mountNode);

注意：受控模式下若不通过onChange更新current，点击页码不会产生任何视觉变化，页码完全由传入的current决定。

场景二：切换每页条数

开启showSizeChanger并监听onShowSizeChange，即可在用户切换每页条数后重新获取数据，见 改变示例：

import { Pagination } from 'antd'; function onShowSizeChange(current, pageSize) { console.log(current, pageSize); } ReactDOM.render( <Pagination showSizeChanger onShowSizeChange={onShowSizeChange} defaultCurrent={3} total={500} />, mountNode);

场景三：迷你分页

在卡片、侧边栏等紧凑布局中推荐使用size="small"，并与showSizeChanger、showQuickJumper、showTotal自由组合，见 迷你示例：

import { Pagination } from 'antd'; function showTotal(total) { return `共 ${total} 条`; } ReactDOM.render(<div> <Pagination size="small" total={50} /> <br /> <Pagination size="small" total={50} showSizeChanger showQuickJumper /> <br /> <Pagination size="small" total={50} showTotal={showTotal} /> </div>, mountNode);

场景四：简洁分页

simple属性适合空间有限或强调极简交互的场景，见 简洁示例：

import { Pagination } from 'antd'; ReactDOM.render( <Pagination simple defaultCurrent={2} total={50} />, mountNode);

场景五：展示数据总数

通过showTotal在分页器左侧展示数据总量。该示例还演示了自定义selectComponentClass将每页条数选择器替换为自定义 Select 的扩展方式，见 总数示例：

import { Pagination, Select } from 'antd'; function showTotal(total) { return `共 ${total} 条`; } ReactDOM.render( <Pagination selectComponentClass={Select} total={80} showTotal={showTotal} pageSize={20} defaultCurrent={1} />, mountNode );

源码实现原理

antd 封装层

components/pagination/index.jsx 是 antd 对rc-pagination的全部封装逻辑，核心只有几十行：

1. 定义一个MiniSelect内部类，继承 antd 的 Select 并固定size="small"（第 6-12 行）；
2. AntPagination渲染时根据size === 'small'决定使用普通 Select 还是 MiniSelect（第 19-22 行）；
3. 将selectPrefixCls="ant-select"与传入的 props 一并透传给rc-pagination（第 24-28 行）；
4. 通过defaultProps注入默认的zh_CNlocale、空className与ant-pagination前缀（第 33-37 行）。

也就是说，antd 的 Pagination 与底层rc-pagination是"薄封装"关系：交互逻辑、页码计算、省略号折叠等全部由rc-pagination完成，antd 负责接入自己的 Select 组件与样式前缀体系，并通过 style/components/pagination.less 提供视觉样式。

底层渲染与样式

分页条通常由"上一页/下一页按钮、页码数字、省略号、快速跳转输入框、每页条数选择器、总数文案"几部分组成，这些区域的样式均定义在 style/components/pagination.less 中，迷你尺寸通过.mini类名生效。如果需要在项目中覆盖分页样式，可以从ant-pagination前缀入手进行定制。

与表格组件的搭配

在实际业务中，分页最常见的落地场景是与 Table 表格组件 配合，通过受控current/pageSize与onChange/onShowSizeChange实现服务端分页，即每次翻页携带页码参数请求新数据。这也是 docs/pattern/complex-table.md 等设计模式文档中反复强调的复杂表格实践：将分页状态提升到页面容器，数据请求与分页状态解耦。

小结

• 最小用法只需total一个属性，antd 会基于defaultPageSize = 10自动生成页码条；
• 掌握受控（current/pageSize）与非受控（defaultCurrent/defaultPageSize）两套用法，服务端分页推荐受控模式；
• showSizeChanger、showQuickJumper、simple、size="small"、showTotal五个开关覆盖了绝大多数产品形态需求；
• 源码层面 antd 对rc-pagination是薄封装，index.jsx 中 MiniSelect 的适配与默认 zh_CN locale 注入值得在定制分页时参考。

【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/gh_mirrors/antde/ant-design