SepPagination 分页组件 v1.0.0

基本分页 · 页码省略 · 总条数 · 每页条数 · 快速跳转 · 首末页 · 简洁模式 · 三种尺寸 · 禁用态 · 受控/非受控 · 自定义渲染

1. 基础用法

功能说明:total 总条数,defaultPageSize 每页条数(默认 10),defaultCurrent 当前页(默认 1)。点击页码切换,onChange 回调返回 (current, pageSize)。≤7 页全部显示,>7 页自动省略首尾。

HTML 声明式标签
JS API 初始化
current: 1, pageSize: 10

2. 总条数显示(showTotal)

showTotal 显示总条数,可传函数 showTotal(total, range) 自定义文案,如「共 500 条」或「显示 11-20 条,共 500 条」。

HTML 声明式标签
JS API 初始化(自定义 total 文案)

3. 每页条数选择(showSizeChanger)

showSizeChanger 显示每页条数下拉,pageSizeOptions 自定义可选值(默认 [10,20,50,100]),onShowSizeChange 回调。切换后若当前页超出范围自动回退。

HTML 声明式标签
JS API 初始化(自定义 options)

4. 快速跳转(showQuickJumper)

showQuickJumper 显示跳转输入框,输入页码后回车跳转,超出范围自动钳制到 [1, totalPages],失焦恢复当前页。

HTML 声明式标签
JS API 初始化

5. 首末页按钮(showFirstLast)

showFirstLast 显示首页/末页按钮(« »),默认开启。点击直接跳转到第 1 页或最后一页。

HTML 声明式标签

6. 简洁模式(simple)

simple 简洁模式,仅显示上一页/下一页和当前页输入框,适合空间有限场景。输入页码回车跳转。

HTML 声明式标签
JS API 初始化

7. 三种尺寸(size)

size 控制尺寸:small / middle(默认)/ large,高度分别为 24px / 32px / 40px。

HTML 声明式标签
small
middle(默认)
large

8. 禁用态(disabled)

disabled 禁用所有交互(页码、上下页、首末页、每页条数、跳转框),视觉降低不透明度。

HTML 声明式标签

9. 受控模式 + API 动态操作

受控模式:通过 current + onChange 外部控制页码(不设置 defaultCurrent)。API:setCurrent / setPageSize / setTotal / setDisabled / getCurrent / getTotalPages。

JS API 初始化
current: 1, pageSize: 10, total: 200

10. 完整组合(总条数 + 每页条数 + 跳转 + 首末页)

所有功能全开的完整分页器,适合列表页底部使用。

HTML 声明式标签
JS API 初始化

11. 单页隐藏(hideOnSinglePage)

hideOnSinglePage 当总页数 ≤ 1 时自动隐藏整个分页器,避免列表底部出现无意义的"1"。

JS API 初始化

12. 页码数量(pagerCount)

pagerCount 控制最多显示几个页码按钮(含首尾和省略号),默认 7。值越大显示的页码越多,适合宽屏场景。

JS API 初始化

13. 切换每页条数重置页码(pageSizeChangeResetCurrent)

pageSizeChangeResetCurrent 切换每页条数时是否自动回到第 1 页。默认 false(保持当前页,超范围则钳制)。

JS API 初始化

14. 自定义导航文字(prevText / nextText / firstText / lastText)

prevText / nextText / firstText / lastText 自定义导航按钮的文字或图标,支持 HTML。

JS API 初始化

15. 自定义渲染(itemRender)

itemRender(page, type, originalElement) 自定义页码及导航按钮的渲染内容。type 取值:page(页码)/ prev / next / first / last / jump-next(省略号)。返回字符串替换文字,返回 HTMLElement 替换内部节点。

JS API 初始化

16. 布局自定义(layout)

layout 用逗号分隔的字符串控制各区块的渲染顺序。可用值:total / sizes / prev / pager / next / first / last / jumper,以及 -> 表示后续区块右对齐。

JS API 初始化
默认顺序(含首末页):total, sizes, first, prev, pager, next, last, jumper
右对齐:prev, pager, next, ->, total, sizes, jumper
首末页放中间:total, first, prev, pager, next, last

17. 响应式适配(responsive)

responsive 开启后,当容器宽度 < 480px 时自动隐藏「每页条数」「快速跳转」「首末页」按钮,仅保留核心页码导航,适配移动端/窄屏。下方示例容器宽度限制为 360px 以展示效果。

JS API 初始化(容器宽度 360px)
同配置但 responsive=false(对比)

18. 细粒度事件(onFirstClick / onPrevClick / onNextClick / onLastClick / onPageClick)

除统一的 onChange 外,还可分别监听首页/上一页/下一页/末页/具体页码的点击事件,便于数据埋点。回调参数为当前页码。

JS API 初始化(点击按钮查看事件日志)

19. 前后缀插槽(prefix / suffix)

prefix / suffix 自定义分页器前后内容,支持字符串、HTMLElement 或函数 (state) => string|Node。需在 layout 中指定 prefix / suffix token 控制位置。

JS API 初始化

20. 加载状态(loading)

loading 加载期间自动锁定所有交互(点击翻页/切换条数/跳转输入),解除后恢复,配合 Table 数据请求使用。setLoading(true/false) 动态切换。

JS API 初始化

21. pageSizeOptions 对象形式

pageSizeOptions 支持 [{ value: 10, label: '10 条/页' }] 对象数组形式,自定义每页条数选项的显示文字。也兼容原有数字数组 [10, 20, 50]。

JS API 初始化(对比:数字数组 vs 对象数组)

22. 自动化断言