简单好用的PHP分页组件，前端样式自由定制

分页是 Web 开发里绕不开的需求，但也是最容易写出“一坨屎”代码的地方。逻辑本身不复杂，无非就是LIMIT和OFFSET那一套，可一旦涉及到和前端样式、页码展示逻辑混在一起反复调整，就很容易变得一团糟。之前我也试过网上搜到的各种代码片段，要么是写死的CSS类名跟Bootstrap深度绑定，换主题得Ctrl+H全局替换；要么是逻辑笨重，为了做二次封装必须继承重写一大堆方法。

基于这些不愉快的经历，我一直想找个轻量级的解决方案，核心诉求就三点：引包够快、调用够简单、渲染出来的HTML完全由我自己说了算。后来自己动手整理了这套分页组件，简直不要太爽，今天具体掰扯掰扯。

没有Controller和View的“历史包袱”

很多通用组件为了体现所谓“全能”，什么都往里塞：又是Query Builder适配，又是DTO模型包装，一看源码，光是构造函数就让你传五个参数。但我这个组件的理念就一个字：简。

它是纯PHP类，不依赖任何框架，你直接把文件拉进项目里 `require` 一下就能用。构造函数只需要三个基本参数：当前页码、总记录数、每页显示条数。其他的配置项，比如URL模式、中间省略符号的表现，都有默认值，你可以按需通过链式调用覆盖。

核心的调用体验是这样的：

$pager = new Paginator($currentPage, $totalRows, $pageSize);
$pager->setUrlTemplate('list?page=(:num)'); // 只需要这一个URL模板
$pager->paginate();

这样，它在不需要查库的情况下就拿到了分页所需的全部数据。为什么连查询都包了？各家的查询构造器千奇百怪，手写的SQL也各有各的套路，不强行耦合，反而用起来更舒服。

样式自由定制原来是真的

既然要“前端样式自由定制”，意味着组件内部绝对不许输出 `<ul class="pagination">` 这种写死的标签结构。我的做法很粗暴，也特别有效——**组件内部只生成数据数组，默认提供一个简单到极致的基础模板，输出交给开发者**。

默认模板长这样：

<nav>
  <a href="{url}">上一页</a>
  <!-- 由数组渲染出的每个页码链接 -->
  <a href="{url}">下一页</a>
</nav>

除了默认模板，我还留了一手，一个 `render(string $style)` 方法。没有东西是写死的，你可以传入你自己手写的HTML片段，比如用包含双引号的复杂嵌套结构。然后在里边用 `{pages}` 这种占位符，让组件把生好的链接List填进去。如果你连 `<a>` 标签的class属性都不想要组件默认帮你加的，那你完全可以只用它拿到数据数组，自己用 `foreach` 遍历生成任何形式的内容。这种自由感，比那种给你预留了一堆 `setPrevBtnText()` 方法的组件强多了。

除了好看，它还能帮你处理头疼的省略号

页码逻辑如果超过了10页，组件能够自动计算：什么情况下显示“省略号”，什么情况下把当前页的前后三页都显示出来。更重要的是，在计算出当前页码范围之后，还需要保证第一页和最后一页始终在导航上。

这套逻辑虽然不复杂，但自己每写一次项目就要重写一遍。现在组件一键拉满，并且输出的HTML结构友好到令人发指：

<a href="...">1</a>
<span class="gap">...</span>
<a href="...">8</a>
<a href="...">9</a>
<span class="current">10</span>
<a href="...">11</a>

你只需要写两行简单的CSS去修饰 `.gap` 和 `.current`，样式效果立马就出来了。这与那些直接把样式连同结构一起输出给前端、导致“想给当前页加个小图标都无处下手”的生成器，简直是两个维度的产物。

纯前端Ajax场景的解放

现在很多交互都是无刷新翻页。传统服务器端分页需要整体刷新页面，这种组件反而更吃香。用这套组件，如果在`render`之前没配置URL模板，它默认生成的就是纯`javascript:void(0);`的链接，并且它会在渲染数据里特意标注`data-page="3"`属性。你在前端只需要用事件委托，抓取带有该属性的元素，拿到页码后自行发起Ajax请求替换局部Dom，这样它就成了一个纯粹的逻辑计算器。

以前无刷新翻页，每次需求变更都要去后台改一大段拼接HTML的字符串，特别容易引号转义出错；现在前端拿到的都是一手数据，想怎么玩就怎么玩。

这组件我从个人项目用到团队项目，从Bootstrap 3时代一直用到现在。好看分页千篇一律，好用的逻辑计算却万里挑一。如果你手里刚好有个分页需求，与其把时间花在和模板标签的作斗争上，不如直接试试这种“计算归计算，展示归展示”的分离设计。