# 分页

分页器，页码数量恒定不跳动，支持每页条数、跳转框、简洁模式、多种尺寸。声明式写 data-zh-pager，或用 ZhaoUI.pager 创建。库不管数据，只管页码，翻页后你自己取数据。

**依赖**：`zhaoui.css` 与 `zhaoui.js`（原生 HTML、CSS、JS，不需要框架或 jQuery）。

## 用法

```html
<nav class="zh-pg" id="pg1" data-zh-pager data-total="486" data-size="10" data-show-size-changer data-show-jumper aria-label="文章分页"></nav>
<nav class="zh-pg" data-zh-pager data-total="200" data-simple aria-label="简洁分页"></nav>

<script>
document.getElementById('pg1').addEventListener('zh:page-change', function (e) {
  console.log('第', e.detail.page, '页，每页', e.detail.size, '条');
});
</script>
```

## 样式类

`zh-pg`

## 属性

| 属性 | 用在 | 取值 | 说明 |
|---|---|---|---|
| `data-zh-pager` | .zh-pg 或任意容器 | 无 | 声明这是一个分页器，用下面的 data-* 配置 |
| `data-total / data-page / data-page-size（等同 data-size）` | 容器 | 整数 | 总条数 / 当前页（默认 1）/ 每页条数（默认 10）。注意：data-size 和 data-page-size 是每页多少条，不是控件大小；控件大小用 data-size-name |
| `data-sizes` | 容器 | 逗号分隔，如 10,20,50 | 每页条数的可选项，配合 data-show-size-changer |
| `data-show-total / data-show-size-changer / data-show-jumper` | 容器 | 布尔属性 | 显示总数（默认开）/ 每页条数选择 / 跳转输入框 |
| `data-simple / data-bordered / data-disabled / data-hide-on-single-page` | 容器 | 布尔属性 | 简洁模式 / 带边框 / 禁用 / 只有一页时隐藏 |
| `data-size-name` | 容器 | sm \| md（默认）\| lg | 控件的大小，不是每页条数（每页条数用 data-page-size） |
| `data-siblings / data-boundary` | 容器 | 整数，默认 1 | 当前页两侧与首尾各保留几个页码 |

## 方法

- `ZhaoUI.pager(el, { total, page, size, ..., onChange })`：命令式创建，返回 { get(), set(partial), go(page) }。选项与上面的 data-* 一一对应（驼峰写法）
- `el.__zhPager.set({ total })`：数据条数变化后更新（例如筛选后），页码会自动收敛到有效范围

## 事件

| 事件 | 触发于 | detail | 说明 |
|---|---|---|---|
| `zh:page-change` | 容器 | { page, size } | 页码或每页条数变化时触发（冒泡） |

## 无障碍

- 当前页带 aria-current="page"，每个页码按钮有「第 N 页」的 aria-label
- 翻页后通过 aria-live 朗读「第 3 页，共 49 页」
- 上一页 / 下一页在首尾时用 aria-disabled，不会丢失焦点
- 页码过多时用「…」按钮，可以一次向前 / 向后跳多页
- 跳转框输入非法页码时标记 aria-invalid 并朗读提示
- 翻页后表格内容要你自己换：库只管页码，监听 zh:page-change 取数据，再用 el.__zhPager.set({ total }) 更新总数

## 常见问题

### 分页是什么？

分页器，页码数量恒定不跳动，支持每页条数、跳转框、简洁模式、多种尺寸。声明式写 data-zh-pager，或用 ZhaoUI.pager 创建。库不管数据，只管页码，翻页后你自己取数据。

### 怎么使用分页？

先在页面里引入 zhaoui.css 和 zhaoui.js（放在 </body> 前，不加 defer），再照本页「用法」里的标记书写；需要用代码控制时，用「方法」里列出的接口。

### 分页有哪些事件？

zh:page-change（页码或每页条数变化时触发（冒泡））。

### 分页有哪些方法？

ZhaoUI.pager(el, { total, page, size, ..., onChange })：命令式创建，返回 { get(), set(partial), go(page) }。选项与上面的 data-* 一一对应（驼峰写法）；el.__zhPager.set({ total })：数据条数变化后更新（例如筛选后），页码会自动收敛到有效范围。

### 分页支持键盘和读屏吗？

当前页带 aria-current="page"，每个页码按钮有「第 N 页」的 aria-label；翻页后通过 aria-live 朗读「第 3 页，共 49 页」；上一页 / 下一页在首尾时用 aria-disabled，不会丢失焦点。

### 分页需要依赖框架吗？

不需要。ZhaoUI 是原生 HTML、CSS 和 JavaScript，不依赖 jQuery、Vue 或 React。