企业官网建设流程全解析

ant-design Pagination 基础分页使用指南：从 basic 示例到完整 API 解析

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

Pagination（分页）是 ant-design 中用于分隔长列表的核心导航组件，核心思路是"每次只加载一个页面"的数据，避免一次性渲染全部数据带来的性能开销。本文以components/pagination/demo/basic.md中的最基础示例为切入点，结合组件源码与其余 8 个演示用例，系统讲解 Pagination 的最小可用写法、受控/非受控模式、尺寸与跳转等完整 API，帮助你在项目中快速落地可复用的分页方案。

最小可用示例：三行代码完成基础分页

components/pagination/demo/basic.md给出了 ant-design Pagination 最精简的用法——只需要传入默认页码和总数两个属性即可渲染出一个完整可交互的分页器：

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

该示例对应的完整实现位于 Pagination 组件。从源码看，ant-design 的 Pagination 是对第三方rc-pagination的二次封装：AntPagination组件内部直接渲染<Pagination selectComponentClass={selectComponentClass} selectPrefixCls="ant-select" {...this.props} className={className} />，并将默认的locale设为zhCN、prefixCls设为ant-pagination（对应样式前缀见 pagination.less）。因此，defaultCurrent、total等所有对外属性都会透传给rc-pagination，由底层完成页码计算与点击交互。

在这个示例中：

• defaultCurrent={1}表示初始时停留在第 1 页（非受控模式的默认值）；
• total={50}表示数据总数为 50 条，在未指定pageSize时按默认每页 10 条计算，共 5 页；
• 点击页码即可切换，组件内部自动更新高亮页码，无需你维护任何状态。

从 basic 到完整用法：Pagination 全量 API 解析

basic.md只是入口，完整的属性定义见 Pagination 文档 的 API 章节。下表即为全部对外可配置参数，实际使用时可与上面rc-pagination透传机制相互印证：

需要特别说明的是：

• current与defaultCurrent的区别在于受控与否：传入current时组件变为受控模式，页码完全由你通过onChange回调配合setState维护；只传defaultCurrent则是非受控模式，组件内部自行维护页码状态；
• onChange的回调参数是改变后的页码，适合在翻页时同步触发数据请求；
• pageSize未指定时，defaultPageSize（默认 10）生效，二者共同决定总页数 =total / pageSize向上取整。

受控模式：用 state 完全接管页码

当页面状态需要与路由、表格筛选等其他逻辑联动时，应使用受控模式，参考 demo/controlled.md：

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} />; } });

这里current与onChange成对出现，形成"state 驱动 → 回调更新 → 重新渲染"的闭环，页码始终与外部状态保持唯一数据源，适用于与服务端交互的列表场景。

每页条数切换：showSizeChanger 与 onShowSizeChange

长列表场景常需允许用户自定义每页条数，参见 demo/changer.md：

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

• showSizeChanger开启后，组件会渲染一个每页条数下拉框，选项由pageSizeOptions决定（默认['10', '20', '30', '40']）；
• 该下拉框在 ant-design 封装层中使用 Select 组件 实现，源码见 index.jsx 中的MiniSelect：当size === 'small'时，会用小尺寸 Select 替换默认 Select 以保持视觉一致；
• onShowSizeChange(current, pageSize)在 pageSize 变化时触发，第一个参数是变化前的当前页。

快速跳转：showQuickJumper

数据量较大、页数较多时，逐页点击效率低，可开启跳转输入框，参考 demo/jump.md：

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

开启后分页器右侧出现数字输入框，输入页码回车即可直达目标页，total={500}时按默认每页 10 条共 50 页，跳转价值尤为明显。

迷你尺寸：size="small"

在空间受限的工具栏、卡片页脚等场景，可使用迷你尺寸，参考 demo/mini.md：

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);

从 组件源码 看，size="small"会做两件事：一是往className追加mini修饰类，二是将每页条数下拉框替换为MiniSelect（小尺寸 Select），从而在整体和局部都呈现紧凑的迷你观感。迷你模式同样支持showSizeChanger、showQuickJumper、showTotal的组合。

简洁模式：simple

只关心"上一页/下一页"与当前页码的轻量场景，可使用simple属性，参考 demo/simple.md：

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

简洁模式隐藏了完整的页码序列，仅保留当前页/总页数信息与前后翻页按钮，适合移动端或极简列表底部。

显示数据总数：showTotal

通过showTotal自定义"共 X 条"的总数提示文案，参考 demo/total.md：

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

• showTotal接收total（数据总数）作为参数，返回需要展示的字符串，可用模板字符串拼接文案；
• 该示例还展示了selectComponentClass={Select}的用法——将 ant-design 的 Select 注入分页器的每页条数下拉框，这一属性正是 封装层源码 中selectComponentClass透传的体现；
• 结合pageSize={20}，total={80}时分页器共 4 页，适合展示固定分页大小的数据表格。

国际化：locale 切换语言

Pagination 默认输出中文文案，切换语言只需传入对应 locale，参考 demo/locale.md：

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

默认支持en_US与zh_CN两种语言。从 locale/en_US.js 可以看出，ant-design 直接复用了rc-pagination/lib/locale/en_US的语言包，zh_CN同理；组件的默认 locale 则被封装层设置为zhCN（见 index.jsx），因此不传locale时默认显示中文。

更多页码与大数据量展示

当数据量进一步增大时，Pagination 会自动折叠多余页码，仅显示首尾与当前页附近的部分页码，参考 demo/more.md：

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

total={500}按默认每页 10 条共 50 页，此时页码过多无法全部平铺，组件以省略号（...）形式折叠中间页，点击省略号可向前/向后展开一页，保证长列表场景下分页器依然简洁可用。这也是 basic 示例（50 条、5 页）所看不到的行为差异。

实战小结：如何按场景选择 Pagination 用法

综合以上源码与演示用例，可总结出如下选型建议：

所有用法均可组合使用（如size="small"与showQuickJumper、showSizeChanger同时开启），且最终属性都会透传给rc-pagination底层实现，样式统一由 ant-pagination 前缀 下的 pagination.less 控制。建议实际项目中优先采用受控模式管理页码，将分页状态与表格数据请求、URL 查询参数保持同步，即可获得清晰、可维护的列表分页体验。

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