★ FEATURED ARTICLE 前端做列表页永远绕不开分页。数据一多页面不可能一次性把所有记录全倒出来总要有个页码导航让用户一条一条翻。我见过不少人遇到分页需求时要么从零开始手写一套要么把后端拼接好的整段HTML直接糊到页面上样式丑、状态乱、复制粘贴三处不一致。其实Bootstrap5内置的分页组件就是一套经过多年打磨、开箱即用的页码导航解决方案它不依赖任何JavaScript库纯HTML加CSS就能把上一页、下一页、页码按钮、禁用态、当前高亮态全部做得干净利落还自带无障碍支持。这篇内容就来聊聊Bootstrap5分页组件的结构、样式玩法、动态渲染思路以及我实际项目中踩过的一些坑适合刚接触Bootstrap5的前端新手也适合需要把分页组件整合进现有项目的后端同学参考。1. 为什么数据一多前端分页组件就得好好选型1.1 分页组件到底解决了什么问题分页的本质是分流。假设后台管理系统里有三万条订单记录一次性渲染到表格里先不说后端查询压力有多大光是浏览器里生成几万个DOM节点页面滚动和筛选操作就会明显卡顿。分页组件要解决的不是怎么把数据在逻辑上分成几页而是用户如何高效地在页与页之间切换并且在这个过程中始终知道自己在哪一页、还能往哪翻。Bootstrap5的pagination组件在这个层面提供了一个统一、可预测的交互模型上一页、页码组、下一页active标识当前页disabled标识不可用的边界状态。对一个多人协作的团队来说统一分页交互还有一个隐性好处就是UI走查和自动化测试都轻松很多因为页面里所有分页都是一个模子刻出来的不存在这个页面的分页在左边那个页面的分页在右边这种问题。1.2 手写分页和直接用Bootstrap5的差别先说手写分页。最简陋的做法是循环输出一串数字中间用空格隔开放在页面底部再配一个上一页/下一页。这种方案不是不能用但维护成本很高。一旦页面多起来不同开发者写出的分页长得很不一样有的用按钮有的用链接高亮态有的加红字有的加背景色到后面根本没法统一。而且很多人会漏掉边界状态比如当前页是第一页时上一页按钮照样可以点点了就报错或者跳到空白页。Bootstrap5分页把这些都标准化了。它的定位是纯样式组件不带JavaScript行为点击事件、页码切换逻辑官方留给你自己实现。初次接触的人可能会觉得这不算一个完整的分页插件但实际用下来会发现这正是它的优点视觉稳定、结构清晰、交互逻辑完全由自己掌控不会像某些第三方分页插件那样被框架绑死升级一下框架版本反而把分页整崩了。我自己的感受是用Bootstrap5分页组件搭一个包含上一页、下一页、五个页码按钮的基础分页能省掉至少三分之一的无样式工作而且基础观感直接及格。对于后台管理系统这种分页出现频率极高的场景省下来的时间非常可观。2. 三个层级一个都不能少pagination/page-item/page-link 的结构细节2.1 最外层ul.pagination的职责一个标准的Bootstrap5分页最外层是ul classpagination。这一层在CSS里被定义为一个flex容器所有li页签都横向排列。你不需要额外给这个ul加d-flex类因为组件自带的样式已经处理好了。一个最基础的分页结构长这样ul classpagination li classpage-item disabled a classpage-link href#上一页/a /li li classpage-item active aria-currentpage a classpage-link href#1/a /li li classpage-item a classpage-link href#2/a /li li classpage-item a classpage-link href#3/a /li li classpage-item a classpage-link href#下一页/a /li /ul最外层ul.pagination还有两个容易被忽略的职责。一是它负责承载尺寸类比如pagination-lg、pagination-sm只能加在这一层加错了地方样式不生效二是当页面在移动端展示时如果你不希望分页条折行堆叠需要在ul上或者父容器上设置flex-wrap相关样式否则页码一多就会换行显得很乱。2.2 li.page-item、a.page-link和状态类的正确搭配分页组件的第二层是li classpage-item第三层是a classpage-link。为什么要分两层而不是直接在li上完成所有样式因为Bootstrap5要考虑点击区域和无障碍语义。page-link承载了实际的可点击样式包括边框、圆角、文字颜色、hover背景色以及点击时的波纹效果page-item则是外层容器主要用来承接active和disabled这两个状态类。换句话说你想让某一项变高亮或者变禁用操作的是li而不是里面的a。很多人在把Bootstrap5组件翻译成后端模板或者前端框架组件时容易顺手把page-link加到一个div上。这会导致两个问题一是点击区域语义不对二是如果页面里有表单page-link挂在div上既不能提交也不能跳转变成一个纯粹的装饰。官方推荐的做法是page-link尽量放在a或button上如果用了button还要记得加typebutton否则在表单里会触发默认的submit行为。2.3 disabled和active的坑类名只是表象先说disabled。给li.page-item加上disabled类之后里面的page-link会自动获得pointer-events: none视觉上是灰色点击也没反应。但这只对鼠标用户有效。如果用户通过键盘Tab键聚焦到这个链接上并按回车某些浏览器依然会触发a href默认跳转。更稳妥的做法是把disabled状态的page-item内部换成span classpage-link或者干脆不写href属性再在JS事件回调里做一层页码边界判断这样双保险才踏实。再说active。类名加上之后当前页码高亮显示人眼很容易识别。但为了让屏幕阅读器准确播报这里是第几页是当前页官方建议在对应li上再加aria-currentpage。这个属性不影响样式却对无障碍测试和自动化断言非常关键。我遇到过不止一次页面看着一切正常自动化测试却报找不到当前页码排查到最后发现是开发漏了aria-current。3. 对齐、尺寸、图标分页的全部玩法3.1 居中还是靠右别用text-align硬怼分页组件的对齐方式大概有三种左对齐、居中对齐、右对齐。默认情况下ul.pagination是一个块级flex容器会占满整行宽度但里面的li只占内容宽度所以整体看起来是左对齐。想让分页条居中有两种常见写法。一种是在ul的外层套一个div classd-flex justify-content-center另一种是直接在ul.pagination上追加justify-content-center工具类。两种都可以我习惯用后者少一层DOM结构。如果是右对齐用justify-content-end。这里有一个高频坑有人下意识地给分页容器加text-center然后发现分页纹丝不动。因为text-align作用于内联元素和文本而li在flex容器里已经变成了flex项目文本对齐对它不生效。所以只要记住一件事——分页组件是flex布局所有对齐操作都走flex工具类。3.2 三档尺寸切换和响应式场景Bootstrap5给分页提供了两档尺寸类pagination-lg和pagination-sm加上默认尺寸一共三档。使用方式很直接把尺寸类加到ul.pagination上ul classpagination pagination-sm !-- 页码项 -- /ul注意位置尺寸类必须和pagination在同一个元素上。我见过有人写a classpage-link pagination-sm这不会生效。因为Bootstrap的SCSS是把尺寸规则定义在.pagination.pagination-sm .page-link作用域下的你把它放到page-link上等于找不到对应的父级规则样式自然石沉大海。在响应式页面里我常用CSS变量来微调分页在小屏设备上的密度。Bootstrap5组件普遍使用CSS变量分页相关的关键参数长这样media (max-width: 576px) { .pagination { --bs-pagination-padding-x: 0.5rem; --bs-pagination-padding-y: 0.25rem; --bs-pagination-font-size: 0.875rem; } }这样做的好处是不需要覆盖Bootstrap自带的.page-link类也不容易误伤其他组件样式。Bootstrap5之前想改组件尺寸你得去倒腾SCSS变量再编译现在用CSS变量在任意层级覆盖就行灵活度完全不一样。3.3 不带文字的箭头分页怎么做很多设计稿里分页条只有前后箭头不放上一页下一页文字。Bootstrap5官方文档给出的标准思路是用字符实体或者SVG图标。最常见的写法li classpage-item a classpage-link href# aria-label上一页 span aria-hiddentruelaquo;/span /a /li li classpage-item a classpage-link href# aria-label下一页 span aria-hiddentrueraquo;/span /a /lilaquo;和raquo;对应«和»双箭头做上一页、下一页足够用了。如果设计稿是单箭头用lsaquo;和rsaquo;。这里最重要的细节是保留aria-label因为文字被删掉之后屏幕阅读器就只能靠这个属性判断按钮的含义了。箭头分页还有一个体验加分项就是给page-link补一个title属性。鼠标悬停时提示上一页/下一页对不熟悉双箭头符号含义的普通用户友好得多。移动端长按也能看到出处提示。4. 让分页活起来动态渲染与Ajax联动的实战思路4.1 用模板字符串生成分页结构Bootstrap5分页组件本身不提供JS能力所以动态渲染通常是自己把页码数据结构拼成HTML字符串再塞进页面的某个容器。假设后端返回的数据长这样{ currentPage: 3, totalPages: 12, totalCount: 234 }用原生JS渲染一个基础分页核心函数可以这么写function renderPagination(container, currentPage, totalPages, onPageChange) { if (totalPages 1) { container.innerHTML ; return; } let html ul classpagination; html li classpage-item ${currentPage 1 ? disabled : }; html a classpage-link href#>container.addEventListener(click, (event) { const link event.target.closest(.page-link); if (!link) return; event.preventDefault(); const page parseInt(link.dataset.page, 10); if (!page || page 1 || page totalPages) return; onPageChange(page); });closest方法会从实际触发元素向上找最近的匹配节点所以即使你点的是page-link内部某个子元素也能正确找到链接。这个写法有一个前提分页容器内部除了page-link不要混入其他可点击元素否则你需要在回调里加更细的判断。我的习惯是给分页容器一个独立ID比如#pagination-container监听只挂在这个节点上避免把页面上其他区域的事件也捞进来。4.3 页码过多时的折叠算法总页数上百时把所有页码一次性渲染出来既不美观也没必要。通用做法是窗口加首尾当前页前后保留固定数量的页码中间用省略号隔开同时永远保留第一页和最后一页作为跳转锚点。下面是一个常用的生成算法function getPageList(currentPage, totalPages, delta 2) { const pages []; const left Math.max(1, currentPage - delta); const right Math.min(totalPages, currentPage delta); if (left 1) pages.push(1); if (left 2) pages.push(...); for (let i left; i right; i) pages.push(i); if (right totalPages - 1) pages.push(...); if (right totalPages) pages.push(totalPages); return pages; }delta 2意味着当前页前后各显示两个连续页码总共五个连续数字。渲染时遇到...就输出一个不带跳转逻辑的li通常配一个disabled样式的page-link文本。这个算法本身不是唯一解但首尾页常驻、中间窗口折叠、省略号代替连续区间的思路是被验证过最稳定的方案。如果产品同学要求跳转至输入框可以在分页条末尾追加一个li里面放一个input加跳转按钮逻辑上直接调用同一个onPageChange回调就好。5. 后端模板引擎输出分页的整合套路5.1 Thymeleaf里的动态输出写法前端动态渲染适合纯前端项目但很多传统项目是后端模板引擎直接渲染页面比如Spring Boot加Thymeleaf、JSP、Django模板等。这种情况下分页HTML可以在服务端渲染输出也可以由模板引擎的循环标签生成。以Thymeleaf为例一段分页输出大致长这样ul classpagination th:if${page.totalPages 1} li classpage-item th:classappend${page.currentPage 1 ? disabled : } a classpage-link th:href{/list(page${page.currentPage - 1})}上一页/a /li li classpage-item th:eachi : ${#numbers.sequence(1, page.totalPages)} th:classappend${i page.currentPage ? active : } th:attraria-current${i page.currentPage ? page : null} a classpage-link th:href{/list(page${i})} th:text${i}1/a /li li classpage-item th:classappend${page.currentPage page.totalPages ? disabled : } a classpage-link th:href{/list(page${page.currentPage 1})}下一页/a /li /ulth:classappend是这里的关键。它会在基础类后面追加内容而不是像th:class那样整段替换。如果你用th:class把page-item整个覆盖掉Bootstrap的样式瞬间就没了。这是后端模板整合时最容易犯的错误代码逻辑明明都对页面样式却奇奇怪怪。5.2 后端分页查询与前端页码的对应关系无论后端用Oracle的ROWNUM分页、MyBatis Plus的Page插件还是JPA的Pageable回到前端分页组件这里需要的数据实际只有几项当前页码、总页数、总记录数以及用来生成链接的查询参数。两个边界公式特别容易写错offset (currentPage - 1) * pageSize当前页从1开始算偏移量时一定要减1。totalPages Math.ceil(totalCount / pageSize)总页数要向上取整不能向下取整。我做过不少代码评审这两个公式是小错误高发区。一旦算错最后一页要么空白要么显示无数据而从用户视角看这个问题往往被误报成前端分页组件坏了。实际是后端返回的总页数本身就算错了。所以我建议前后端各写各的分页计算工具方法统一单元测试覆盖边界值不要在页面代码里临时拼一个totalPages。还有一点搜索类列表的分页链接除了page参数通常还要带上keyword、status、sortOrder等查询条件。手动拼接URL字符串时条件里的特殊字符很容易破坏链接结构模板引擎的URL表达式会帮忙转义比字符串硬拼安全得多。这也是为什么在老项目里我倾向于优先用模板渲染而不是前端拼接。6. 我反复踩过的四个坑希望你不用再踩6.1 disabled的a标签点击后依然会跳转前面提到过disabled类只是CSS层面的禁用。我实际遇到过一个线上事故分页按钮在第一页时上一页显示为灰色但用户用键盘操作依然可以激活链接页面跳到?page0后端查询报错接口直接500。排查原因就是链接的href还在。现在我的处理方式是disabled状态下直接把a换成span只保留page-link类不写href不响应点击。这样从HTML语义上就彻底切断了跳转路径。Bootstrap5官方文档也支持这种做法active和disabled状态的page-link都可以换成span classpage-link。6.2 pagination-sm写错位置导致样式失效这个问题我在尺寸那一节已经分析过原理。这里补一个实际排查思路遇到分页尺寸不生效先打开浏览器的开发者工具看ul.pagination的计算样式。如果font-size和padding没有任何变化第一步检查尺寸类是不是和pagination在同一个元素上第二步检查自己的CSS是不是写了类似.page-link { padding: 10px 15px }这种规则把组件的CSS变量覆盖了。现在Bootstrap5的组件尺寸本质上由--bs-pagination-padding-x、--bs-pagination-padding-y这些变量控制。定制分页时不要直接去改.page-link的padding而是覆盖这些变量这样既不会破坏组件内部其他规则也能和尺寸类自然共存。6.3 动态渲染时没做HTML转义动态渲染分页代码看起来只是拼字符串但如果页码或者其他数据来自用户输入、第三方系统没有转义就直接插进innerHTML就可能埋下存储型XSS的隐患。绝大多数情况下页码是后端算出的整数风险不大但如果你的分页条附近出现了搜索关键词、标签名这类用户可控文本就要小心。最简单的防御是给所有不可信字符串包一层转义函数function escapeHtml(str) { const div document.createElement(div); div.textContent str; return div.innerHTML; }渲染时对每个动态值都过一遍这个函数。分页组件只是页面上很小的一块代码但它也是用户直接触达的交互入口别因为简单就跳过这一步。6.4 只加active没写aria-current自动化测试容易翻车人眼看到高亮就觉得当前页状态没毛病但自动化测试判断当前页时通常会查li.page-item.active或者aria-currentpage。如果页面里还有其他地方也用到了active类测试脚本定位当前页会更加依赖aria-current。所以我现在养成了一个习惯要active就必带aria-currentpage两者成对出现谁也别省。另一个细节是aria-current的合法值应该是page不是true也不是current。写错值虽然不影响视觉但无障碍工具读出来会是错的。这类属性错误不会让页面报错也不会让样式崩坏只会在无障碍检测和自动化断言时暴露出来属于最隐蔽的一类问题。如果你现在的项目里分页还是各处手写、样式五花八门、边界状态全靠临场发挥的状态建议抽个半天统一换成Bootstrap5这套然后大家在同一个基础上再去做封装和扩展。我自己切换过来之后就很少再为分页样式操心了更多精力花在了页码的折叠策略和交互细节上这才是分页组件真正值得琢磨的地方。
阅读完成 · 觉得有帮助？
