# 二、Pager 母型「设计规范表」（以后你扩 20×5 不会再炸）

这是**核心内容**，你以后所有 pager 都应该**严格遵守**。

---

## ① Pager 的“冻结粒度”设计（非常关键）

### ✅ 正确冻结方式（你刚才已经悟对了）

> **分页只绑定域名，不绑定页面、不绑定页码**

```php
pagerCfg = [
  family  => 'numeric' | 'pill' | 'block' | 'input' | 'minimal',
  variant => 0~19,        // 子变体
  tone    => 1~N          // 色调 / 强弱
]
```

* category / search **共用一套 pagerCfg**
* 不同域名 = 不同 pager
* 翻页时 HTML **不变化**（SEO + F12 都稳定）

❌ 错误方式：

* 每一页重新随机
* pager 跟随页码变化
* 搜索和分类用不同 pagerCfg（没必要）

---

## ② Pager 母型（Family）定义标准（5 个）

| 母型  | family  | 结构特征           | 适用    |
| --- | ------- | -------------- | ----- |
| 数字型 | numeric | 页码 + prev/next | 绝大多数  |
| 药丸型 | pill    | 圆角 / 胶囊        | 移动端   |
| 块状型 | block   | 方块 / 网格        | PC    |
| 输入型 | input   | 页码输入框          | 高级站   |
| 极简型 | minimal | prev / next    | SEO 页 |

**每个 family = 1 个文件**
例如：`pager_01.html`、`pager_02.html`

---

## ③ 每个母型必须包含的「功能元素」（硬性）

任何 pager（无论多花哨），**必须全部考虑**：

| 元素              | 必须 |
| --------------- | -- |
| 上一页 prev        | ✅  |
| 下一页 next        | ✅  |
| 首页 first        | 推荐 |
| 末页 last         | 推荐 |
| 当前页 current     | ✅  |
| disabled 状态     | ✅  |
| aria-current    | ✅  |
| rel="prev/next" | 推荐 |

❌ 不允许再出现：

* 没有 prev/next
* 只有页码
* 没有 current 高亮

---

## ④ 子变体（Variant）的**正确扩展方式**

**Variant ≠ 改逻辑**
**Variant 只改结构 + 视觉**

### ✅ 允许变的（安全）

* 外层标签：`nav / section / footer / aside`
* 容器结构：`ul/li` ↔ `div/span`
* 顺序：`prev → pages → next` / `pages → prev/next`
* 视觉：

  * 圆角 / 方角
  * 边框 / 无边框
  * 实心 / outline / ghost
* 信息增强：

  * “第 X / Y 页”
  * “共 N 页”

### ❌ 不允许变的（会炸）

* `$pagerArr` 的遍历方式
* prev / next 的判断逻辑
* current / disabled 的语义判断

---

## ⑤ 安全数据规则（你这次踩坑的核心）

### ❌ 禁止写法

```tpl
$pagerArr[1]['url']
$pagerArr[3]['url']
```

### ✅ 唯一允许

```php
foreach ($pagerArr as $it) {
  if ($it['type'] === 'page') {
    if ($first_url === null) $first_url = $it['url'];
    $last_url = $it['url'];
  }
}
```

然后模板里只用：

```tpl
{:$first_url ?? '#'}
{:$last_url ?? '#'}
```

---

## ⑥ CSS 规范（和你 CssBuilder 完全兼容）

### 必须遵守

* **所有 class 带 `$TpStyle.dom_prefix`**
* CSS 用 `__PFX__`，由 CssBuilder 替换
* 不写死颜色，只用：

  * `var(--color_primary)`
  * `var(--color_bg)`
  * `var(--color_border)`

### 推荐结构

```
pager_base.css        // 所有 pager 共用
pager_01_numeric.css  // 仅 numeric
pager_02_pill.css
...
```

---

## 七、你现在处在什么阶段（实话）

你现在已经做到：

* ✅ 架构方向完全正确
* ✅ 冻结逻辑清晰
* ✅ item / pager 思路统一
* ❌ 之前炸的都是 **模板语法 + PHP/TP 边界问题**

这一轮修完后，**不会再出现那种“越改越乱”的情况了**。

---