Material UI Pagination 分页组件详解siblingCount、受控模式、usePagination Hook 与路由集成实战【免费下载链接】material-uiMaterial UI: Comprehensive React component library that implements Googles Material Design. Free forever.项目地址: https://gitcode.com/GitHub_Trending/ma/material-ui本文以 Material UIMUI官方文档 Pagination 组件页 为主体覆盖从基础用法、页码范围裁剪siblingCount/boundaryCount、受控分页、路由集成到无头 HookusePagination的完整技术脉络并结合 Pagination 组件源码 给出每个属性的默认值与底层实现依据帮助你在博客、电商列表、后台表格等真实场景中正确选择Pagination或TablePagination并写出可复制运行的分页代码。组件定位与源码结构Pagination组件让用户从一个页面范围中选择特定页码。它适用于「不使用无限加载」时对任意条目列表进行分页的场景官方文档明确指出在SEO 很重要的上下文例如博客中优先使用Pagination而对大量表格数据分页则应使用TablePagination组件。组件的源码位于 packages/mui-material/src/Pagination 目录核心文件包括Pagination.js组件主体负责将usePagination返回的条目映射为PaginationItem并管理焦点逻辑paginationClasses.ts定义MuiPagination的类名工具root、ul、outlined、text配套的无头 HookusePagination位于 packages/mui-material/src/usePagination与条目组件PaginationItem位于packages/mui-material/src/PaginationItem三者共同构成分页体系的完整分层。基础用法最简示例只需count总页数一个必填语义的属性其余全部有默认值。基础示例见 BasicPaginationimport Pagination from mui/material/Pagination; export default function BasicPagination() { return Pagination count{10} /; }从 Pagination.js 源码 中解构出的默认值可以确认各属性缺省行为属性默认值说明count1总页数page—当前页受控从 1 开始defaultPage1非受控模式下的初始页码varianttext外观变体可选outlinedshapecircular页码按钮形状可选roundedsizemedium尺寸可选small、largecolorstandard选中页颜色支持主题调色板颜色siblingCount1当前页前后各显示几页boundaryCount1首尾固定显示几页showFirstButton/showLastButtonfalse是否显示「首页 / 末页」按钮hidePrevButton/hideNextButtonfalse是否隐藏「上一页 / 下一页」按钮renderItem(item) PaginationItem {...item} /自定义每个分页条目的渲染外观变体变体、形状与尺寸文档提供了三组外观示例分别对应variant、shape、size三个属性Outlined paginationvariantoutlined示例见 PaginationOutlinedRounded paginationshaperounded示例见 PaginationRoundedPagination sizesizesmall或large示例见 PaginationSize。在样式层面Pagination.js 中根节点被styled(nav)定义overridesResolver会按ownerState.variant叠加outlined/text对应的类名内部ul固定为 flex 布局、flexWrap: wrap、无列表样式因此分页天然支持窄容器下的换行展示。首页 / 末页按钮与隐藏前后翻页按钮文档的 Buttons 章节说明可以可选地启用首页、末页按钮或禁用上一页、下一页按钮。示例见 PaginationButtons对应属性为showFirstButton、showLastButton、hidePrevButton、hideNextButton四个布尔属性均可自由组合。一个容易踩的边界情况被源码显式处理了当你在第 1 页点击「首页/上一页」、或在末页点击「下一页/末页」时该按钮点击后会变为 disabled。如果此时焦点正停留在该按钮上焦点会「丢失」handleItemClick 与焦点恢复逻辑 会把焦点记录到pendingFocusRef并在selectedPage更新后自动把焦点移到带aria-currentpage的选中页上。使用usePagination自行渲染时需要注意复刻这一行为。自定义控制图标文档说明控制图标前后翻页箭头可以自定义示例见 CustomIcons通过showFirstButton、showLastButton与自定义renderItem将PaginationItem的箭头替换为自定义 SVG/图标即可。页码范围siblingCount 与 boundaryCount这是Pagination最核心的两个数字属性siblingCount控制页码省略号两侧显示的数字个数相对当前页boundaryCount控制首尾页号旁固定显示的页码个数。官方示例 PaginationRanges 展示了四组组合count{11}、defaultPage{6}Stack spacing{2} Pagination count{11} defaultPage{6} siblingCount{0} / Pagination count{11} defaultPage{6} / {/* Default ranges */} Pagination count{11} defaultPage{6} siblingCount{0} boundaryCount{2} / Pagination count{11} defaultPage{6} boundaryCount{2} / /Stack结合默认值siblingCount1、boundaryCount1默认渲染形如1 … 5 6 7 … 11将siblingCount设为 0 则只剩当前页与边界页将boundaryCount设为 2 则首尾各固定显示两页。这两个参数共同决定了条目数组中page、start-ellipsis、end-ellipsis三类条目的分布其裁剪逻辑全部收敛在usePagination内部组件层只负责渲染。受控分页非受控模式下用defaultPage指定初始页onChange回调签名是onChange(event, page)其中page从 1 开始。受控模式则由外部状态接管核心写法对应 PaginationControlled 示例export default function PaginationControlled() { const [page, setPage] React.useState(1); const handleChange (event, value) { setPage(value); }; return Pagination page{page} count{10} onChange{handleChange} /; }传入page后组件进入受控模式页码变化只会触发onChange需要你在回调中更新状态Pagination的pageprop 从 1 开始编号源码 PropTypes 注释亦强调这一点见 Pagination.js。路由集成renderItem 自定义组件对于需要把页码写进 URL 的场景SEO 友好文档的 Router integration 章节给出了标准做法通过renderItem把PaginationItem的component换成路由的Link。完整可运行的 PaginationLink 示例function Content() { const location useLocation(); const query new URLSearchParams(location.search); const page parseInt(query.get(page) || 1, 10); return ( Pagination page{page} count{10} renderItem{(item) ( PaginationItem component{Link} to{/inbox${item.page 1 ? : ?page${item.page}}} {...item} / )} / ); }要点renderItem接收的每个item都携带page、type、selected、onClick等字段展开为PaginationItem的 props 即可第 1 页的 URL 刻意不带查询参数保证首页链接干净可分享。无头 HookusePagination文档明确usePagination()是一个无头 Hook面向高级定制场景暴露它接受与Pagination组件几乎相同的选项只是去掉了所有与 JSX 渲染相关的 propPagination组件正是构建在这个 Hook 之上的。import usePagination from mui/material/usePagination;Hook 的返回值为{ items, ... }items中每一项的type取值包含first、previous、page、next、last、start-ellipsis、end-ellipsis。UsePagination 官方示例 演示了完全自行渲染遍历items对start-ellipsis/end-ellipsis渲染省略号「…」对page类型渲染原生button选中时加粗其余类型渲染翻页按钮并手动实现「点击后按钮禁用时移动焦点到首/末页」的无障碍逻辑——这正是 Pagination.js 中 handleItemClick 所做的事情说明 Hook 使用者需要自行保证焦点管理的等价行为。TablePagination与表格配套的另一种分页文档特别提示为大型表格数据分页应使用TablePagination组件可参考文档 table 章节的 custom pagination options 内容。两者最关键的差异在页码起点Pagination的page从1开始以匹配「页码要出现在 URL 中」的需求TablePagination的page从0开始以匹配渲染大量表格数据时零基 JavaScript 数组切片的需求items.slice(page * rowsPerPage, ...)。因此在混合使用两个组件时务必做page的 ±1 换算这是实际项目中最常见的 off-by-one 错误来源。无障碍Accessibility文档的 Accessibility 章节包含两部分均已在源码中得到印证ARIA根节点默认带有rolenavigation源码中即渲染为nav和aria-labelpagination navigation见 Pagination.js 第 158 行每个分页条目都会获得说明其用途的aria-label例如 go to first page、go to previous page、go to page 1。这些文案默认由 defaultGetAriaLabel 生成type page时返回Go to page N选中页则无前缀Go to其他类型返回Go to ${type} page。可本地化的文案可通过getItemAriaLabelprop 覆盖其签名为(type, page, selected) string。键盘分页条目处于 Tab 顺序中tabindex 为 0配合上文提到的焦点恢复逻辑键盘用户在翻页后焦点会稳定落在新的选中页上。样式类名与定制paginationClasses.ts 导出了MuiPagination的全部类名root根元素、ul列表容器、outlinedvariantoutlined时、textvarianttext时可配合sx、classesprop 或主题components.MuiPagination.styleOverrides做样式覆盖。小结Material UI 的Pagination以「组件 无头 Hook」双层设计覆盖从开箱即用到完全自渲染的分页需求variant/shape/size/color控制外观siblingCount/boundaryCount控制页码范围showFirstButton/showLastButton/hidePrevButton/hideNextButton控制导航按钮renderItem打通路由集成usePagination则把条目计算逻辑开放给定制场景而表格数据分页请切换到TablePagination并注意两者页码起点1 基 vs 0 基的差异。所有属性默认值均可在 packages/mui-material/src/Pagination/Pagination.js 中逐一对应验证。【免费下载链接】material-uiMaterial UI: Comprehensive React component library that implements Googles Material Design. Free forever.项目地址: https://gitcode.com/GitHub_Trending/ma/material-ui创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考