Ant Design分页控件自定义：Pagination与样式定制

Ant Design分页控件自定义：Pagination与样式定制

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

在数据展示类应用中，分页控件（Pagination）是提升用户体验的关键组件。Ant Design提供的Pagination组件不仅支持基础分页功能，还通过灵活的API和样式定制能力满足多样化场景需求。本文将从功能配置到样式定制，详解如何打造符合业务需求的分页控件。

核心功能配置

基础分页实现

Ant Design Pagination组件的基础用法通过设置total（总条数）和defaultCurrent（默认页码）即可快速实现分页功能。核心实现代码位于components/pagination/Pagination.tsx，其封装了rc-pagination的核心能力。

基础示例代码：

import { Pagination } from 'antd';

// 基础分页
<Pagination defaultCurrent={1} total={50} />

// 带页码跳转
<Pagination showQuickJumper defaultCurrent={2} total={500} />

完整基础用法示例可参考components/pagination/demo/basic.tsx和components/pagination/demo/jump.tsx

分页行为定制

Pagination提供三类核心事件回调实现交互逻辑定制：

• onChange: 页码变更时触发，参数为当前页码
• onShowSizeChange: 每页条数变更时触发，参数为当前页码和新页大小
• itemRender: 自定义页码按钮渲染，支持替换默认分页按钮

自定义页码渲染示例：

const itemRender = (_, type, originalElement) => {
  if (type === 'prev') return <a>上一页</a>;
  if (type === 'next') return <a>下一页</a>;
  return originalElement;
};

<Pagination total={500} itemRender={itemRender} />

完整示例见components/pagination/demo/itemRender.tsx

样式定制方案

组件Token定制

通过ConfigProvider的theme.token配置可修改分页控件的核心样式参数。支持定制的主要Token包括：

• paginationFontSize: 字体大小
• paginationItemSize: 页码按钮尺寸
• paginationItemBg: 页码按钮背景色
• paginationItemActiveBg: 当前页码背景色

实现代码：

import { ConfigProvider, Pagination } from 'antd';

<ConfigProvider
  theme={{
    token: {
      paginationItemSize: 36,
      paginationItemActiveBg: '#1677ff',
      paginationFontSize: 14,
    },
  }}
>
  <Pagination defaultCurrent={3} total={500} />
</ConfigProvider>

完整Token定制示例见components/pagination/demo/component-token.tsx

边框模式与紧凑样式

通过配置wireframe主题参数可启用边框模式，适合后台系统表格场景：

<ConfigProvider theme={{ token: { wireframe: true } }}>
  <Pagination showSizeChanger defaultCurrent={3} total={500} />
</ConfigProvider>

紧凑模式通过size="small"属性实现：

<Pagination size="small" total={50} />

边框模式实现原理见components/pagination/Pagination.tsx#L119的BorderedStyle引入逻辑

布局与对齐方式

Pagination支持通过align属性控制分页控件在容器中的对齐方式，可选值为start、center、end：

// 居右对齐分页
<Pagination align="end" defaultCurrent={1} total={50} />

对齐方式示例见components/pagination/demo/align.tsx

高级应用场景

受控模式实现

通过current和onChange实现页码状态完全受控，适用于需要与URL参数或全局状态同步的场景：

import { useState } from 'react';
import { Pagination } from 'antd';

const [current, setCurrent] = useState(1);

const onChange = (page) => {
  setCurrent(page);
  // 可同步更新URL或全局状态
};

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

完整受控模式示例见components/pagination/demo/controlled.tsx

国际化配置

Pagination组件支持通过ConfigProvider配置分页文案，满足多语言需求：

import { ConfigProvider, Pagination } from 'antd';
import zhCN from 'antd/locale/zh_CN';

<ConfigProvider locale={zhCN}>
  <Pagination total={50} />
</ConfigProvider>

组件内部国际化实现逻辑见components/pagination/Pagination.tsx#L104的useLocale调用

禁用状态与加载状态

• 通过disabled属性禁用整个分页控件
• 结合Spin组件实现加载状态（需自定义实现）

禁用状态示例：

<Pagination showSizeChanger defaultCurrent={3} total={500} disabled />

禁用状态示例见components/pagination/demo/component-token.tsx#L40

最佳实践总结

1. 基础使用：优先使用非受控模式(defaultCurrent)，减少状态管理复杂度
2. 样式定制：简单样式用style属性，系统级样式用ConfigProvider.token
3. 性能优化：大数据场景建议设置showLessItems减少页码按钮渲染
4. 可访问性：自定义itemRender时需保持原有关联属性(如aria-label)

完整API文档可参考官方类型定义components/pagination/Pagination.tsx#L20的PaginationProps接口定义。

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