SepPagination 分页组件 v1.0.0
基本分页 · 页码省略 · 总条数 · 每页条数 · 快速跳转 · 首末页 · 简洁模式 · 三种尺寸 · 禁用态 · 受控/非受控 · 自定义渲染
1. 基础用法
功能说明:total 总条数,defaultPageSize 每页条数(默认 10),defaultCurrent 当前页(默认 1)。点击页码切换,onChange 回调返回 (current, pageSize)。≤7 页全部显示,>7 页自动省略首尾。
2. 总条数显示(showTotal)
showTotal 显示总条数,可传函数 showTotal(total, range) 自定义文案,如「共 500 条」或「显示 11-20 条,共 500 条」。
3. 每页条数选择(showSizeChanger)
showSizeChanger 显示每页条数下拉,pageSizeOptions 自定义可选值(默认 [10,20,50,100]),onShowSizeChange 回调。切换后若当前页超出范围自动回退。
4. 快速跳转(showQuickJumper)
showQuickJumper 显示跳转输入框,输入页码后回车跳转,超出范围自动钳制到 [1, totalPages],失焦恢复当前页。
5. 首末页按钮(showFirstLast)
showFirstLast 显示首页/末页按钮(« »),默认开启。点击直接跳转到第 1 页或最后一页。
6. 简洁模式(simple)
simple 简洁模式,仅显示上一页/下一页和当前页输入框,适合空间有限场景。输入页码回车跳转。
7. 三种尺寸(size)
size 控制尺寸:small / middle(默认)/ large,高度分别为 24px / 32px / 40px。
8. 禁用态(disabled)
disabled 禁用所有交互(页码、上下页、首末页、每页条数、跳转框),视觉降低不透明度。
9. 受控模式 + API 动态操作
受控模式:通过 current + onChange 外部控制页码(不设置 defaultCurrent)。API:setCurrent / setPageSize / setTotal / setDisabled / getCurrent / getTotalPages。
10. 完整组合(总条数 + 每页条数 + 跳转 + 首末页)
所有功能全开的完整分页器,适合列表页底部使用。
11. 单页隐藏(hideOnSinglePage)
hideOnSinglePage 当总页数 ≤ 1 时自动隐藏整个分页器,避免列表底部出现无意义的"1"。
12. 页码数量(pagerCount)
pagerCount 控制最多显示几个页码按钮(含首尾和省略号),默认 7。值越大显示的页码越多,适合宽屏场景。
13. 切换每页条数重置页码(pageSizeChangeResetCurrent)
pageSizeChangeResetCurrent 切换每页条数时是否自动回到第 1 页。默认 false(保持当前页,超范围则钳制)。
14. 自定义导航文字(prevText / nextText / firstText / lastText)
prevText / nextText / firstText / lastText 自定义导航按钮的文字或图标,支持 HTML。
15. 自定义渲染(itemRender)
itemRender(page, type, originalElement) 自定义页码及导航按钮的渲染内容。type 取值:page(页码)/ prev / next / first / last / jump-next(省略号)。返回字符串替换文字,返回 HTMLElement 替换内部节点。
16. 布局自定义(layout)
layout 用逗号分隔的字符串控制各区块的渲染顺序。可用值:total / sizes / prev / pager / next / first / last / jumper,以及 -> 表示后续区块右对齐。
17. 响应式适配(responsive)
responsive 开启后,当容器宽度 < 480px 时自动隐藏「每页条数」「快速跳转」「首末页」按钮,仅保留核心页码导航,适配移动端/窄屏。下方示例容器宽度限制为 360px 以展示效果。
18. 细粒度事件(onFirstClick / onPrevClick / onNextClick / onLastClick / onPageClick)
除统一的 onChange 外,还可分别监听首页/上一页/下一页/末页/具体页码的点击事件,便于数据埋点。回调参数为当前页码。
19. 前后缀插槽(prefix / suffix)
prefix / suffix 自定义分页器前后内容,支持字符串、HTMLElement 或函数 (state) => string|Node。需在 layout 中指定 prefix / suffix token 控制位置。
20. 加载状态(loading)
loading 加载期间自动锁定所有交互(点击翻页/切换条数/跳转输入),解除后恢复,配合 Table 数据请求使用。setLoading(true/false) 动态切换。
21. pageSizeOptions 对象形式
pageSizeOptions 支持 [{ value: 10, label: '10 条/页' }] 对象数组形式,自定义每页条数选项的显示文字。也兼容原有数字数组 [10, 20, 50]。