Ant Design Pagination 设计规范：从页面导航行为到交互与样式变体

Ant Design Pagination 设计规范从页面导航行为到交互与样式变体【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/GitHub_Trending/an/ant-design本文基于 ant-design 组件仓库中 Pagination 的设计规范文档components/pagination/index.$tab-design.en-US.md展开系统讲解分页组件的核心设计意图——控制单页信息量并支持页面导航以及少量页码、大量页码两种基础用法、调整每页条数、快速跳转、了解数据总量三种交互变体和简单模式、迷你尺寸、自定义上一步/下一步三种样式变体。读完后你将能够为不同数据规模选择正确的分页形态复制仓库中可直接运行的设计示例代码并理解这些行为在Pagination.tsx源码中的实现依据。一、组件定义分页的行为模型规范文档开篇给出了 Pagination 的本质定义The essence of Pagination is to control the amount of information on a single page and enable page navigation.分页的本质是控制单页展示的信息量并支持页面导航。围绕这一定义文档配套了一个行为模式图Behavior Map其源码位于 behavior-pattern.tsx。从源码结构看该图定义了 1 个核心 MVP 行为与 3 个扩展行为正好对应后文的全部示例行为 ID英文名称中文名称定位链接示例200000004Navigate Pages跳转页面根节点-500000061Jump to Specific Page跳转至指定页面MVP最小可用行为基础用法示例200000005Adjust Items Per Page调整单页展示条数扩展page-size示例200000006Quick Jump快速跳转扩展quick-jump示例200000007Understand Total Data了解数据总量扩展total示例这意味着设计者将点击页码跳到指定页视为分页组件最小可用的核心能力其余能力每页条数、跳转框、总数提示都是在此基础上的渐进增强。该行为图通过.dumi/theme/common/BehaviorMap组件渲染与 Breadcrumb、DatePicker、Alert、Progress 等组件的设计页采用同一套行为建模方式。二、基础用法按页码规模选择形态规范文档将基础用法拆成两种场景并各自给出了选型建议tip。2.1 少量页码Few Pages适用建议内容少于 10 页的轻量分页场景只显示页码数字。对应示例源码 basic.tsximport React from react; import { Pagination } from antd; const App: React.FC () ( Pagination defaultCurrent{2} total{50} showSizeChanger{false} / ); export default App;这里total{50}、默认每页 10 条共 5 页因此只渲染紧凑的页码序列并显式关闭showSizeChanger以隐藏每页条数选择器。2.2 大量页码Large Amount of Pages适用建议内容超过 10 页的场景。此时分页需要让用户快速定位当前页——保留首尾页码中间页码以省略号折叠。对应示例源码 large-amount.tsximport React from react; import { Pagination } from antd; const App: React.FC () ( Pagination defaultCurrent{5} total{100} showSizeChanger{false} / ); export default App;两种形态的差异完全由total触发的页码数量决定页码项的折叠渲染由底层rc-component/pagination完成。在 Pagination.tsx 中可以看到 antd 层负责向 RcPagination 注入折叠图标jumpPrevIcon/jumpNextIcon使用DoubleLeftOutlined/DoubleRightOutlined配合EllipsisOutlined生成跳转省略节点Pagination.tsx#L248-L274并依据direction在 RTL 布局下自动镜像左右箭头保证省略号导航在从右到左的文档环境下依然语义正确。三、交互变体在核心导航之上的渐进增强3.1 调整每页条数Adjust Items Per Page让用户按需调整单页展示条数。对应示例源码 page-size.tsximport React from react; import { Pagination } from antd; const App: React.FC () ( Pagination defaultCurrent{3} total{500} / ); export default App;注意这里没有显式传showSizeChanger——因为total{500}已超过阈值每页条数选择器会自动出现。这个自动逻辑的默认值可在 API 文档 中查到totalBoundaryShowSizeChanger默认值为50当total大于它时showSizeChanger自动为true。实现上分两层showSizeChanger属性的归一化。useShowSizeChanger.ts 将该属性解析为[是否显示, SelectProps]元组传boolean时返回[showSizeChanger, {}]传对象即 SelectProps时返回[true, showSizeChanger]不传时返回[undefined, undefined]把决定权交给全局配置或totalBoundaryShowSizeChanger阈值。组件内属性与 ConfigProvider 上下文配置按属性优先合并Pagination.tsx#L148-L155。每页条数选择器的渲染。sizeChangerRender内部默认使用 antd 的SelectshowSearch、popupMatchSelectWidth{false}并将弹出层挂载到triggerNode.parentNode见 Pagination.tsx#L197-L218。从 6.6.0 起还支持components.sizeChanger传入自定义组件只需接收value、onChange、disabled、className四个 propsPagination.tsx#L175-L185。默认每页条数defaultPageSize为10pageSizeOptions默认[10, 20, 50, 100]见 API 文档。3.2 快速跳转Quick Jump当数据量大、用户需要精确定位时输入页码直接跳页。对应示例源码 quick-jump.tsximport React from react; import { Pagination } from antd; const App: React.FC () ( Pagination defaultCurrent{3} total{500} showQuickJumper / ); export default App;showQuickJumper支持boolean或{ goButton: ReactNode }两种取值后者可自定义跳转确认按钮见 API 文档。3.3 了解数据总量Understand Total Data让用户无需浏览全部数据即可理解数据总量常用于表格的数据统计展示。对应示例源码 total.tsximport React from react; import { Pagination } from antd; import useLocale from ../../../../.dumi/hooks/useLocale; const locales { cn: { total: (total: number, current: string | number) 第 ${current} 条 / 共 ${total} 条, }, en: { total: (total: number, current: string | number) ${current} of ${total} items, }, }; const App: React.FC () { const [locale] useLocale(locales); return ( Pagination defaultCurrent{3} total{500} showQuickJumper showTotal{(total, range) locale.total(total, range.join(-))} / ); }; export default App;showTotal的签名为function(total, range)range是[当前页首条序号, 当前页末条序号]的数组示例中用range.join(-)拼成区间文本。示例还同时开启了showQuickJumper展示总量提示 快速跳转的组合形态。四、样式变体适配不同空间约束4.1 简单分页Simple Pagination只展示当前页、总页数与上一步/下一步导航适合模块内横向空间受限的场景。对应示例源码 simple.tsximport React from react; import { Pagination } from antd; const App: React.FC () ( Pagination defaultCurrent{2} total{50} showSizeChanger{false} simple / ); export default App;simple支持boolean或{ readOnly?: boolean }readOnly用于禁止通过上一步/下一步修改页码见 API 文档。4.2 迷你分页Mini Pagination小尺寸的分页控件适合空间受限且只需轻量页导航的模块内场景。对应示例源码 mini.tsx通过Flex垂直排列展示了 5 种 mini 形态的组合import React from react; import { Flex, Pagination } from antd; // ...locales 定义同 total.tsx省略 const App: React.FC () { const [locale] useLocale(locales); return ( Flex vertical gapmedium Pagination defaultCurrent{1} total{50} showSizeChanger{false} sizesmall / Pagination defaultCurrent{1} total{100} showSizeChanger{false} sizesmall / Pagination defaultCurrent{1} total{100} sizesmall / Pagination defaultCurrent{1} total{100} showQuickJumper sizesmall / Pagination defaultCurrent{1} total{100} showQuickJumper sizesmall showTotal{(total, range) locale.total(total, range.join(-))} / /Flex ); }; export default App;关于小尺寸Pagination.tsx 中的逻辑值得注意Pagination.tsx#L118-L120const mergedSize useSize(customizeSize); const isSmall mergedSize small || !!(xs !mergedSize responsive);即 mini 形态不仅由显式sizesmall或 ConfigProvider 的sizesmall触发当开启responsive且窗口宽度断点为xs、且组件未显式指定size时也会自动退化为小尺寸。同时源码保留了向后兼容的ant-pagination-miniclass 别名并在sizeclass 中输出ant-pagination-small。4.3 自定义上一步/下一步Prev and Next规范文档最后一个样式变体引用了组件主文档中的itemRender示例itemRender.tsx把上一步/下一步从箭头图标改为文字链接import React from react; import type { PaginationProps } from antd; import { Pagination } from antd; const itemRender: PaginationProps[itemRender] (_, type, originalElement) { if (type prev) { return aPrevious/a; } if (type next) { return aNext/a; } return originalElement; }; const App: React.FC () Pagination total{500} itemRender{itemRender} /;itemRender的签名为(page, type: page | prev | next, originalElement) React.ReactNode对未处理的type返回originalElement即可保持默认渲染不变。五、延伸阅读从设计规范到完整 API设计规范页回答的是什么场景用哪种形态而完整的属性契约current、pageSize、showLessItems、align、hideOnSinglePage、onChange(page, pageSize)、onShowSizeChange(current, size)等 20 余项配置含类型、默认值与可用版本号以及 Semantic DOM 定制点classNames/styles支持对root、item语义节点定制和设计 Token 列表均可在 Pagination API 文档 中查阅。结合本文与源码的关键文件索引规范主体components/pagination/index.$tab-design.en-US.md行为模式定义components/pagination/design/behavior-pattern.tsx各设计示例源码components/pagination/design/demo/basic / large-amount / page-size / quick-jump / total / simple / mini 共 7 个组件实现components/pagination/Pagination.tsxsizeChanger 归一化components/pagination/useShowSizeChanger.ts完整 API 与 Tokencomponents/pagination/index.en-US.md【免费下载链接】ant-designAn enterprise-class UI design language and React UI library项目地址: https://gitcode.com/GitHub_Trending/an/ant-design创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考