代码演示
如何引入
<script setup lang="ts">
import { Pagination } from '@fibrous/semi-ui-vue';
</script>基本
基础分页，通过 total 设置总条数，pageSize 设置每页容量
代码
<script setup lang="ts">
import { Pagination } from '@fibrous/semi-ui-vue';
</script>
<template>
<div>
<Pagination :style="{ marginBottom: '12px' }" :total="30" />
<Pagination :style="{ marginBottom: '12px' }" :total="80" />
<Pagination :style="{ marginBottom: '12px' }" :total="200" />
<Pagination :pageSize="30" :style="{ marginBottom: '12px' }" :total="80" />
</div>
</template>禁用
通过 disabled 设置禁用
代码
<script setup lang="ts">
import { Pagination } from '@fibrous/semi-ui-vue';
</script>
<template>
<Pagination disabled :style="{ marginBottom: '12px' }" :total="30" />
</template>总页数显示
通过 showTotal 属性控制是否展示总页数
- 总页数：8
- 总页数：20
代码
<script setup lang="ts">
import { Pagination } from '@fibrous/semi-ui-vue';
</script>
<template>
<div>
<Pagination showTotal style="margin-bottom: 12px" :total="80" />
<Pagination showTotal style="margin-bottom: 12px" :total="200" />
</div>
</template>指定当前页码
可以通过 defaultCurrentPage 指定当前激活的页码
- 总页数：8
代码
<script setup lang="ts">
import { Pagination } from '@fibrous/semi-ui-vue';
</script>
<template>
<div>
<Pagination :defaultCurrentPage="3" showTotal :total="80" />
</div>
</template>每页容量切换
通过设置 showSizeChanger 为 true，允许通过 Select 组件快速切换每页容量
- 每页条数：10
- 每页条数：10
代码
<script setup lang="ts">
import { Pagination } from '@fibrous/semi-ui-vue';
</script>
<template>
<div>
<Pagination showSizeChanger style="margin-bottom: 12px" :total="80" />
<Pagination showSizeChanger :total="300" />
</div>
</template>快速跳转至某页
通过设置 showQuickJumper 为 true, 允许通过Input控件输入页码，快速跳转
当Input失去焦点时，若Input中为有效数字，会直接进行跳转。你亦可在Input聚焦时，输入期望跳转的页码后直接敲击回车进行跳转
若你输入页码大于分页器总页数，我们会自动为你跳转至最后一页
- 跳至页
- 跳至页
代码
<script setup lang="ts">
import { Pagination } from '@fibrous/semi-ui-vue';
</script>
<template>
<div>
<Pagination showQuickJumper style="margin-bottom: 12px" :total="80" />
<Pagination showQuickJumper :total="300" />
</div>
</template>页码受控
用 v-model:currentPage 绑定页码，分页器即为受控组件，当前激活页码完全取决于绑定的值；也可以只传 currentPage 并监听 @pageChange 自行更新
代码
<script setup lang="ts">
import { ref } from 'vue';
import { Pagination } from '@fibrous/semi-ui-vue';
const page = ref(3);
</script>
<template>
<Pagination v-model:currentPage="page" :total="200" />
</template>预设每页容量可选值
传入 pageSizeOpts 数组，指定切换每页容量的可选值
- 每页条数：50
- 每页条数：10
代码
<script setup lang="ts">
import { Pagination } from '@fibrous/semi-ui-vue';
</script>
<template>
<div>
<Pagination :pageSizeOpts="[50, 80, 90, 200]" showSizeChanger style="margin-bottom: 12px" :total="300" />
<Pagination :pageSizeOpts="[10, 20, 50, 200]" showSizeChanger :total="300" />
</div>
</template>迷你版本
size 设置为 small
- 1/9
代码
<script setup lang="ts">
import { Pagination } from '@fibrous/semi-ui-vue';
</script>
<template>
<Pagination size="small" :total="90" />
</template>开启 hoverShowPageSelect，可以 hover 页码打开页码列表快速切换
代码
<script setup lang="ts">
import { Pagination } from '@fibrous/semi-ui-vue';
</script>
<template>
<Pagination hoverShowPageSelect size="small" :total="90" />
</template>API 参考
Props
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| total | 总条数。 | number | semiDefault("Pagination", "total", 1) |
| showTotal | 是否显示总页数，size 为 small 时不显示。 | boolean | semiDefault("Pagination", "showTotal", false) |
| pageSize | 每页条数，未传时取 pageSizeOpts 的第一项。非严格受控：每页条数选择器的选择保留在组件内部，只有该属性变为与当前不同的值时才会覆盖它，并回到第 1 页（受控时回到 currentPage）；用 v-model:pageSize 回写选择器的结果不会重置页码。 | number | semiGlobalDefault("Pagination", "pageSize") |
| pageSizeOpts | 每页条数选择器的可选值；当前每页条数不在其中时按大小插入选项。 | number[] | TypesemiDefault("Pagination", "pageSizeOpts", [...numbers.PAGE_SIZE_OPTION]) |
| size | 尺寸，可选 default 或 small。 | "small" | "default" | semiDefault("Pagination", "size", "default") |
| currentPage | 当前页码，对应 v-model:currentPage；传入后分页器受控，不传（undefined）时由组件自己管理。 | number | semiGlobalDefault("Pagination", "currentPage") |
| defaultCurrentPage | 非受控时的初始页码。 | number | semiDefault("Pagination", "defaultCurrentPage", 1) |
| showSizeChanger | 是否显示每页条数选择器，size 为 small 时不生效。开启后 hideOnSinglePage 不再生效。 | boolean | semiDefault("Pagination", "showSizeChanger", false) |
| showQuickJumper | 是否显示快速跳转输入框，总页数小于 2 时禁用。 | boolean | semiDefault("Pagination", "showQuickJumper", false) |
| popoverPosition | 省略页码浮层与每页条数下拉的位置。未传时每页条数下拉为 bottomLeft（RTL 下 bottomRight），省略页码浮层使用 Popover 的默认位置 bottom；size 为 small 时不使用。 | Type"top" | "bottom" | "left" | "right" | "topLeft" | "topRight" | "leftTop" | "leftBottom" | "rightTop" | "rightBottom" | "bottomLeft" | "bottomRight" | "leftTopOver" | "rightTopOver" | "leftBottomOver" | "rightBottomOver" | semiGlobalDefault("Pagination", "popoverPosition") |
| hideOnSinglePage | 总页数小于 2 时是否隐藏分页器；每页条数选择器显示时不生效。 | boolean | semiDefault("Pagination", "hideOnSinglePage", false) |
| hoverShowPageSelect | 仅 size 为 small 时生效：悬停或聚焦页码文字时打开页码列表。 | boolean | semiGlobalDefault("Pagination", "hoverShowPageSelect") |
| disabled | 是否禁用。 | boolean | semiDefault("Pagination", "disabled", false) |
| preventPageChangeOnPageSizeChange | 切换每页条数时保持当前页码，新页码由使用方在 pageSizeChange 中决定。 | boolean | semiDefault("Pagination", "preventPageChangeOnPageSizeChange", false) |
Events
| 事件 | 说明 | 回调参数 |
|---|---|---|
| update:currentPage | 页码变化时触发，用于 v-model:currentPage。 | [currentPage: number] |
| update:pageSize | 每页条数变化时触发，用于 v-model:pageSize。 | [pageSize: number] |
| pageChange | 页码变化时触发。 | [currentPage: number] |
| pageSizeChange | 每页条数变化时触发。 | [pageSize: number] |
| change | 页码或每页条数变化时触发。 | [currentPage: number, pageSize: number] |
Slots
| 插槽 | 说明 | 作用域参数 |
|---|---|---|
| prevText | 替换上一页按钮的图标。纯文本时按钮以该文字命名，其他内容（图标、元素）仍使用语言包的名称；插槽为空时保留默认图标与语言包名称。 | any |
| nextText | 替换下一页按钮的图标，命名规则同 prevText。 | any |
Exposes
| 名称 | 说明 | 类型 |
|---|---|---|
| 无 |
class、style 与原生属性（id、aria-*、data-*、事件监听）经 attrs 落在根元素 ul 上，default 与 small 两种尺寸一致；change 已声明为组件事件，@change 只收到页码与每页条数，不会收到快速跳转输入框冒泡的原生 change 事件。ref 取到的是组件实例，根元素为实例的 $el。
Accessibility
Pagination 按 WAI-ARIA 分页导航 的常见做法实现。
ARIA
- 根元素是
ul，每一项（总数、上一页、页码、下一页、每页条数、快速跳转）都是其中的li - 上一页、下一页、页码和「…」都是原生
button。页码的名称为「第 N 页」，「…」为「更多」，上一页、下一页按钮默认以语言包文案命名；传入prevText、nextText（Vue 中为同名插槽）且内容是纯文本时以该文字命名，图标、元素等其他内容仍使用语言包文案 - 当前页的按钮带
aria-current="page"；禁用的按钮使用原生disabled - 快速跳转输入框以「跳至」命名，总页数小于 2 时禁用
- 组件本身不是导航地标。页面上的分页是主要导航手段时，建议包在
<nav aria-label="...">里，并用名称区分页面上的多个分页
键盘和焦点
- 上一页、下一页、页码和「…」都可以用
Tab聚焦，Enter或Space翻页； - 键盘聚焦「…」或 small 模式下开启
hoverShowPageSelect的页码文字时，会打开被省略的页码列表：下箭头聚焦列表中的第一页，上箭头聚焦最后一页；- 在列表中用
Tab、Shift + Tab移动，Enter或Space跳到该页； Esc关闭列表，焦点回到触发按钮。
设计变量
下表是组件内部的 Sass 变量，不能覆写。定制样式请覆写 --semi-* CSS 变量（见 Design Token 页），或写不分层的 CSS 规则。
| Sass 变量 | 值 | 用法 |
|---|---|---|
| $transition_duration-pagination_item-bg | var(--semi-transition_duration-none) | 翻页器页码-背景色-动画持续时间 |
| $transition_function-pagination_item-bg | var(--semi-transition_function-easeIn) | 翻页器页码-背景色-过渡曲线 |
| $transition_delay-pagination_item-bg | var(--semi-transition_delay-none) | 翻页器页码-背景色-延迟时间 |
| $transition_duration-pagination_item-text | var(--semi-transition_duration-none) | 翻页器页码文本-背景色-动画持续时间 |
| $transition_function-pagination_item-text | var(--semi-transition_function-easeIn) | 翻页器页码文本-背景色-过渡曲线 |
| $transition_delay-pagination_item-text | var(--semi-transition_delay-none) | 翻页器页码文本-背景色-延迟时间 |
| $transform_scale-pagination_item | var(--semi-transform_scale-none) | 翻页器item-放大 |
| $color-pagination-text-default | var(--semi-color-text-2) | 翻页器总页数文本颜色 |
| $color-pagination_item-text-default | var(--semi-color-text-0) | 翻页器 页码 文本颜色 |
| $color-pagination_item-icon-default | var(--semi-color-tertiary) | 翻页器 页码 图标颜色 |
| $color-pagination_item-text-hover | var(--semi-color-text-0) | 翻页器 页码 悬浮态文本颜色 |
| $color-pagination_item-bg-hover | var(--semi-color-fill-0) | 翻页器 页码 悬浮态背景颜色 |
| $color-pagination_item-text-active | var(--semi-color-text-0) | 翻页器 页码 按下态文字颜色 |
| $color-pagination_item-bg-active | var(--semi-color-fill-1) | 翻页器 页码 按下态背景颜色 |
| $color-pagination_item-text-disabled | var(--semi-color-disabled-text) | 翻页器 页码 禁用态文字颜色 |
| $color-pagination_item-icon-disabled | var(--semi-color-disabled-text) | 翻页器 页码 禁用态图标颜色 |
| $color-pagination_item-bg-disabled | transparent | 翻页器 页码 禁用态背景颜色 |
| $color-pagination_item-bg-selected-disabled | var(--semi-color-disabled-fill) | 翻页器 页码 选中禁用态背景颜色 |
| $color-pagination_item-text-selected | var(--semi-color-primary) | 翻页器 页码 选中态文字颜色 |
| $color-pagination_item-bg-selected | var(--semi-color-primary-light-default) | 翻页器 页码 选中态背景颜色 |
| $color-pagination_quickjump_text-disabled | var(--semi-color-disabled-text) | 翻页器 快速跳转禁用态文字颜色 |
| $color-pagination_item-border-default | transparent | 翻页器 页码 默认边框颜色 |
| $color-pagination_item-border-hover | transparent | 翻页器 页码 悬浮边框颜色 |
| $color-pagination_item-border-active | transparent | 翻页器 页码 激活边框颜色 |
| $color-pagination_item-border-selected | transparent | 翻页器 页码 选中边框颜色 |
| $color-pagination_item-border-disabled | transparent | 翻页器 页码 禁用边框颜色 |
| $height-pagination_item | 32px | 翻页器 页码高度 |
| $width-pagination_item-minWidth | 32px | 翻页器 页码最小宽度 |
| $width-pagination_item_small-minWidth | 44px | 迷你翻页器 页码最小宽度 |
| $width-pagination_quickjump_input_width | 50px | 快速跳转输入框宽度 |
| $width-pagination_item_border | 0px | 翻页器 页码 默认边框宽度 |
| $spacing-pagination-padding | 0 | 翻页器内边距 |
| $spacing-pagination_small-paddingY | 0 | 迷你翻页器垂直内边距 |
| $spacing-pagination_small-paddingX | 0 | 迷你翻页器水平内边距 |
| $spacing-pagination_item-marginLeft | $spacing-extra-tight | 翻页器页码左侧外边距 |
| $spacing-pagination_item-marginRight | $spacing-extra-tight | 翻页器页码右侧外边距 |
| $spacing-pagination_item_small-margin | 0 | 迷你翻页器页码外边距 |
| $spacing-pagination_reset_list-paddingTop | $spacing-extra-tight | |
| $spacing-pagination_reset_list-paddingBottom | $spacing-extra-tight | |
| $spacing-pagination_quickjump_marginLeft | 24px | 快速跳转左侧外边距 |
| $spacing-pagination_quickjump_input_marginLeft | 4px | 快速跳转输入框左侧外边距 |
| $spacing-pagination_quickjump_input_marginRight | 4px | 快速跳转输入框右侧外边距 |
| $radius-pagination_item | var(--semi-border-radius-small) | 翻页器页码圆角大小 |
| $font-pagination_small-fontWeight | $font-weight-regular | 迷你翻页器字重 |
| $font-pagination_item-fontWeight | $font-weight-regular | 翻页器页码字重 |
| $font-pagination_item_active-fontWeight | $font-weight-bold | 翻页器页码选中态字重 |