Pagination
在多页数据之间切换。中文惯用名：分页。
稳定本期新增已接入
元信息
| 字段 | 值 |
|---|---|
| 规范 ID | component.pagination |
| 名称 | Pagination |
| 二级分类 | 导航（navigation） |
| 用途 | 在多页数据之间切换 |
| 描述 | 中文惯用名：分页。 |
预览
静态结构：渲染为 <nav aria-label="pagination" data-slot="pagination"> → PaginationContent（data-slot="pagination-content"，ul）→ 每项 PaginationItem（data-slot="pagination-item"）。首尾为 PaginationPrevious / PaginationNext（Chevron 图标；sm 断点以上附 Previous / Next 文案，aria-label 为 Go to previous / next page），不可用时 aria-disabled + 禁用样式且点击无效；中间为页码链接 PaginationLink（data-slot="pagination-link"，当前页 data-active + 分页激活令牌描边底色）与省略号 PaginationEllipsis（MoreHorizontal 图标）。页码由 ceil(total / pageSize) 推导（至少 1 页）；页码窗口：总页数 ≤ 7 全部展示，否则按当前页位置取 7 项窗口（当前页靠前 → 1~5 + 省略 + 末页；靠后 → 首页 + 省略 + 末 5 页；居中 → 首页 + 省略 + 当前页±1 + 省略 + 末页）。本预览为受控用法：page 驱动 state，点击经 events.onChange 回写。
DSL 结构
{
"type": "Pagination",
"props": {
"total": 95,
"pageSize": 10,
"page": "${state.page}"
},
"events": {
"onChange": {
"action": "setState",
"params": {
"page": "${event}"
}
}
}
}何时用
何时使用
- 在多页数据之间切换：表格、卡片列表、搜索结果的分页浏览。
- 用户需要定位到具体页或全局页码感知：需要显示「共 N 页」的量级信息时。
- 服务端分页：total + pageSize 来自接口，page 受控并驱动下一次请求。
何时不用
- 浏览型信息流（下拉加载更多）：使用无限滚动。
- 数据量小（一页内可展示完）：不渲染分页。
- 只需要「上一页 / 下一页」的场景：当前适配器固定渲染完整页码序列，轻量场景可考虑用 Button 组自建。
变体
| 变体 | 视觉形态 | 适用场景 |
|---|---|---|
| 受控分页 | page 由 state 驱动，onChange 回写并触发取数 | 服务端分页的表格 / 列表 |
| 非受控分页 | 不传 page，组件内部自管理当前页 | 纯前端切分已加载数据 |
| 短序列（≤7 页） | 页码全显，无省略号 | 数据量中等的列表 |
| 长序列（>7 页） | 省略号 + 7 项窗口滑动 | 大数据量结果集 |
API 属性
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
total | number | 0 | 总条数（可绑表达式解析后的数字）；页数 = ceil(total / pageSize)，至少 1 |
pageSize | number | 10 | 每页条数 |
page | number | — | 受控当前页（可绑 ${state.x}）；缺省内部自管理 |
onChange | (page: number) => void | — | 翻页事件，传出目标页码 number（Renderer 绑定 events.onChange）；上一页 / 下一页与页码点击走同一事件 |
className / style | string / CSSProperties | — | 通用：根节点 class 合并 / 内联样式 |
使用规范
- 分页状态是单一数据源：受控时由 page 驱动取数，不在组件内外各存一份当前页。
- 改变筛选条件 / 每页条数时把 page 重置为 1，避免落在越界页。
- pageSize 与 total 来自同一份接口响应，页码数量才不会与数据不一致。
- 分页旁给出结果量级（共 N 条 / 每页 M 条），帮助用户判断翻页范围。
- 翻页时列表区域给出加载态，避免用户重复点击翻页。
正例
- ✓ 表格分页：total={95} pageSize={10} page 绑 state，onChange 触发 setState 并重新取数。
- ✓ 搜索结果：结果数较多时展示分页，同时显示「共 95 条」辅助信息。
反例
- ✕ 在无限滚动列表底部再放分页（两种浏览模型冲突）。
- ✕ 把 page 作为独立于数据请求的本地状态（翻页后数据与页码不同步）。
Design Token 映射
不适用：组件 tokenRefs 为空：样式 Token 数据尚未接入，三层映射（Primitive → Semantic → Component）待样式 Token 接入后回填。