Pagination 分页
数据分页导航，支持页码省略、前后翻页、自定义相邻页码数、总数展示、每页条数切换与快速跳转。
基础用法
基础用法
页码省略
多页省略
相邻页码数
siblings 控制
页码上限
pager-count 页码按钮数量上限
超过上限时按当前页居中收缩窗口，省略号两端至少留 2 页（首尾页始终可达）；低于最小值 5 回落 5 并在控制台告警。
总条数
show-total 显示总条数
每页条数切换
page-sizes 每页条数下拉
切换每页条数后回到第 1 页并派发 oas-change，detail: { page: 1, pageSize }。
条数切换器阈值
total-boundary 控制条数切换器显隐
设置 total-boundary 后，仅 total 大于阈值才渲染每页条数下拉；未设置时维持现状（有 page-sizes 即显示）。
快速跳转
show-jumper 跳至指定页
输入页码后回车跳转（越界自动夹取到合法范围），派发 oas-change，detail: { page, pageSize }。
组合用法
总数 + 每页条数 + 快速跳转
翻页事件
oas-change 事件
禁用状态
disabled 全局禁用
尺寸
size 五档（xs / sm / md / lg / xl）
默认 md；非法值回落 md 并在控制台告警。
极简模式
simple 极简形态
极简形态只渲染前后钮与「当前 / 总页数」文本，与页码省略算法互斥（simple 优先）。
总数未知形态
show-more 总数未知
show-more 用于总数未知的场景：不渲染页码序列与总数，仅三钮形态；show-jumper / page-sizes / hide-on-single 均不适用（无总页数概念）。
首末页
show-edges 首末页钮
单页隐藏
hide-on-single 单页不渲染
自定义图标
prev-icon / next-icon 插槽
提供 slot="prev-icon" / slot="next-icon" 内容时替换默认箭头 ‹ / ›。
自定义总数
total 插槽
有 slot="total" 内容时替换内置「共 N 条」文案；show-total 布尔仍兼容（无插槽内容时显示内置文案）。
翻页拦截
oas-before-change 拦截
oas-before-change 在翻页/跳转前派发，detail: { page }；宿主 preventDefault() 可取消本次变更（本示例拦截跳转到第 4 页）。切换每页条数不拦截。
受控模式
受控 current
外部按钮直接设置 current 属性驱动视图跳页（越界自动夹取）；组件自身翻页同样派发 oas-change 并回写属性。
边界场景
单页 / 首尾禁用
链接模式
href-template 渲染为链接
设置 href-template（含 {page} 占位符）后，页码/前后/首末钮渲染为 <a href>，{page} 替换为目标页码；target 属性透传 <a target>。禁用时降级为 span（不可点）。点击仍派发 oas-change，oas-before-change 取消时会同时阻止原生导航。
响应式
responsive 窄屏自动切极简
省略号跳页
省略号可点击跳页
省略号渲染为可点击按钮，点击向该侧跳 siblings + 1 页（受 oas-before-change 拦截与边界夹取约束）；aria-label 走 i18n（向前跳页/向后跳页）。
自定义页码内容
page-item 插槽模板
宿主放入含 {page} 占位符的模板内容，组件对每个页码钮克隆该内容并把 {page} 文本替换为实际页码（仅 textContent 替换，防注入）；未提供插槽时显示纯页码数字。prev/next/首尾钮不受影响。
API
oas-pagination
属性
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
current | 当前页（受控，翻页会更新该属性） | string | 1 |
disabled | 全局禁用：分页钮全部禁用并带 aria-disabled，每页条数下拉与跳转输入框禁用 | boolean | — |
hide-on-single | 单页（pageCount ≤ 1）时整个组件不渲染 | boolean | — |
href-template | 链接模式：设置后页码/前后/首末钮渲染为 <a href>（{page} 占位符替换为目标页），中键/右键/新标签原生可用；disabled 时降级为不可点击的 span | string | — |
page-size | 每页条数 | string | 10 |
page-sizes | 每页条数下拉选项（JSON 数组），如 [10,20,50]；切换后回到第 1 页 | string | — |
pager-count | 页码按钮（不含前后/首末页钮）的最大可见数量，默认 9；超过上限时按当前页居中收缩窗口（省略号两端至少留 2 页，首尾页可达），低于最小值 5 回落 5 并告警 | string | 9 |
responsive | 响应式：组件宽度 < 640px 时自动按 simple 极简形态渲染（ResizeObserver 监听容器宽度，恢复后还原）；与显式 simple 等效 | boolean | — |
show-edges | 显示首/末页双箭头钮（« »），边界处禁用；aria-label 走 i18n | boolean | — |
show-jumper | 显示「跳至 __ 页」快速跳转输入框（回车跳转，越界夹取） | boolean | — |
show-more | 总数未知形态：total ≤ 0 时渲染「上一页 / 更多 / 下一页」三钮（更多钮为不可点状态指示，样式对齐页码钮但弱化；prev/next 点击 current±1 并派发 oas-change）；total > 0 时无效走正常页码渲染；show-jumper / page-sizes / hide-on-single 均不适用 | boolean | — |
show-total | 显示总条数文案「共 X 条」 | boolean | — |
siblings | 当前页前后各显示的页码数 | string | 1 |
simple | 极简形态：只渲染前后钮与「当前 / 总页数」文本，与页码省略算法互斥（simple 优先）；show-jumper 可叠加 | boolean | — |
size | 尺寸档位：xs / small / medium（默认）/ large / xl；sm/md/lg 为等价别名；非法值回落 medium 并在控制台告警 | string | medium |
target | 链接模式下透传给 <a target>（如 _blank）；仅在设置 href-template 时生效 | string | — |
total | 总条数 | string | 0 |
total-boundary | 条数切换器显隐阈值：设置后仅 total 大于该值才渲染每页条数下拉（total ≤ 阈值隐藏）；未设置时维持现状（有 page-sizes 即显示） | string | — |
事件
| 事件 | 说明 |
|---|---|
oas-before-change | 翻页/跳转前派发，可 preventDefault 取消本次变更（切换每页条数不派发）；链接模式下同时阻止原生导航，detail: { page } |
oas-change | 翻页 { page }；切换每页条数 { page: 1, pageSize }；快速跳转 { page, pageSize }，detail: { page } | { page: 1, pageSize } | { page, pageSize } |
插槽
| 名称 | 说明 |
|---|---|
next-icon | 下一页按钮图标插槽，有内容时替换默认 › |
page-item | 页码内容自定义插槽：宿主放入含 {page} 占位符的模板内容（如 <span slot="page-item" hidden>第 {page} 页</span>），组件对每个页码钮克隆该内容并替换占位符（仅 textContent，防注入）；未提供时显示纯页码数字；prev/next/首尾钮不受影响 |
prev-icon | 上一页按钮图标插槽，有内容时替换默认 ‹ |
total | 总条数文案插槽，有内容时替换内置「共 N 条」 |
CSS 变量
| CSS 变量 | 默认值 |
|---|---|
--oas-pagination-font | var(--oas-font-size-md) |
--oas-pagination-height | var(--oas-control-height-md) |
页码超出范围时自动省略，首尾翻页按钮在边界自动禁用。