组件
    切换框架
    ReactVueSolidSvelte
    切换语言
    简体中文English
    GitHub
    导航类

    翻页器

    分页器帮助用户在多个页之间进行导航

    代码演示

    如何引入

    <script lang="ts">
    import { Pagination } from '@fibrae/semi-ui-svelte';
</script>

    基本

    基础分页，通过 total 设置总条数，pageSize 设置每页容量

    代码
    <script lang="ts">
    import { Pagination } from '@fibrae/semi-ui-svelte';
</script>

<div>
    <Pagination style="margin-bottom: 12px" total={30} />
    <Pagination style="margin-bottom: 12px" total={80} />
    <Pagination style="margin-bottom: 12px" total={200} />
    <Pagination pageSize={30} style="margin-bottom: 12px" total={80} />
</div>

    禁用

    通过 disabled 设置禁用

    代码
    <script lang="ts">
    import { Pagination } from '@fibrae/semi-ui-svelte';
</script>

<Pagination disabled style="margin-bottom: 12px" total={30} />

    总页数显示

    通过 showTotal 属性控制是否展示总页数

    • 总页数：8
    • 总页数：20
    代码
    <script lang="ts">
    import { Pagination } from '@fibrae/semi-ui-svelte';
</script>

<div>
    <Pagination showTotal style="margin-bottom: 12px" total={80} />
    <Pagination showTotal style="margin-bottom: 12px" total={200} />
</div>

    指定当前页码

    没有 defaultCurrentPage，直接传 currentPage={3} 作初始页码即可；点击翻页后页码成为组件内部的本地值。

    • 总页数：8
    代码
    <script lang="ts">
    import { Pagination } from '@fibrae/semi-ui-svelte';
</script>

<div>
    <Pagination currentPage={3} showTotal total={80} />
</div>

    每页容量切换

    通过设置 showSizeChanger 为 true，允许通过 Select 组件快速切换每页容量

    代码
    <script lang="ts">
    import { Pagination } from '@fibrae/semi-ui-svelte';
</script>

<div>
    <Pagination showSizeChanger style="margin-bottom: 12px" total={80} />
    <Pagination showSizeChanger total={300} />
</div>

    快速跳转至某页

    通过设置 showQuickJumper 为 true, 允许通过Input控件输入页码，快速跳转
    当Input失去焦点时，若Input中为有效数字，会直接进行跳转。你亦可在Input聚焦时，输入期望跳转的页码后直接敲击回车进行跳转
    若你输入页码大于分页器总页数，我们会自动为你跳转至最后一页

    • 跳至
      页
    • 跳至
      页
    代码
    <script lang="ts">
    import { Pagination } from '@fibrae/semi-ui-svelte';
</script>

<div>
    <Pagination showQuickJumper style="margin-bottom: 12px" total={80} />
    <Pagination showQuickJumper total={300} />
</div>

    页码受控

    用 bind:currentPage 绑定页码；用 bind:currentPage={get, set} 可让分页器完全受控，由 setter 决定是否接受新页码。不传 currentPage 时页码由组件自己管理。

    代码
    <script lang="ts">
    import { Pagination } from '@fibrae/semi-ui-svelte';

    let page = $state(3);
</script>

<Pagination bind:currentPage={page} total={200} />

    预设每页容量可选值

    传入 pageSizeOpts 数组，指定切换每页容量的可选值

    代码
    <script lang="ts">
    import { Pagination } from '@fibrae/semi-ui-svelte';
</script>

<div>
    <Pagination pageSizeOpts={[50, 80, 90, 200]} showSizeChanger style="margin-bottom: 12px" total={300} />
    <Pagination pageSizeOpts={[10, 20, 50, 200]} showSizeChanger total={300} />
</div>

    迷你版本

    size 设置为 small

    • 1/9
    代码
    <script lang="ts">
    import { Pagination } from '@fibrae/semi-ui-svelte';
</script>

<Pagination size="small" total={90} />

    开启 hoverShowPageSelect，可以 hover 页码打开页码列表快速切换

    代码
    <script lang="ts">
    import { Pagination } from '@fibrae/semi-ui-svelte';
</script>

<Pagination hoverShowPageSelect size="small" total={90} />

    API 参考

    Props

    属性说明类型默认值
    currentPage当前页码，可用 bind:currentPage 双向绑定；不传时由组件自己管理页码，用 bind:currentPage={get, set} 完全受控。number-
    disabled是否禁用。booleanfalse
    hideOnSinglePage总页数小于 2 时是否隐藏分页器；每页条数选择器显示时不生效。booleanfalse
    hoverShowPageSelect仅 size 为 small 时生效：悬停或聚焦页码文字时打开页码列表。boolean-
    nextText替换下一页按钮图标的字符串或 snippet，命名规则同 prevText。string | Snippet-
    onChange页码或每页条数变化时调用，参数为页码与每页条数。Type(currentPage: number, pageSize: number) => void-
    onPageChange页码变化时调用。Type(currentPage: number) => void-
    onPageSizeChange每页条数变化时调用。Type(pageSize: number) => void-
    pageSize每页条数，可用 bind:pageSize 绑定，选择器的选择会写回；未传时取 pageSizeOpts 的第一项。number-
    pageSizeOpts每页条数选择器的可选值；当前每页条数不在其中时按大小插入选项。number[][10, 20, 40, 100]
    popoverPosition省略页码浮层与每页条数下拉的位置；size 为 small 时不使用。Position-
    preventPageChangeOnPageSizeChange切换每页条数时保持当前页码，新页码由使用方在 onPageSizeChange 中决定。booleanfalse
    prevText替换上一页按钮图标的字符串或 snippet。字符串或纯文本 snippet 作为按钮名称，其他内容（图标、元素）仍使用语言包的名称；传入空 snippet 时按钮为空，空字符串则显示默认图标。string | Snippet-
    showQuickJumper是否显示快速跳转输入框，总页数小于 2 时禁用。booleanfalse
    showSizeChanger是否显示每页条数选择器，size 为 small 时不显示。booleanfalse
    showTotal是否显示总页数，size 为 small 时不显示。booleanfalse
    size尺寸，可选 default 或 small。'small' | 'default'"default"
    total总条数。number1

    class、style 与原生属性和事件（如 id、aria-*、data-*、onclick）落在根元素 ul 上，default 与 small 两种尺寸一致；onChange、onPageChange、onPageSizeChange 是组件回调，不落在根元素上。

    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-bgvar(--semi-transition_duration-none)翻页器页码-背景色-动画持续时间
    $transition_function-pagination_item-bgvar(--semi-transition_function-easeIn)翻页器页码-背景色-过渡曲线
    $transition_delay-pagination_item-bgvar(--semi-transition_delay-none)翻页器页码-背景色-延迟时间
    $transition_duration-pagination_item-textvar(--semi-transition_duration-none)翻页器页码文本-背景色-动画持续时间
    $transition_function-pagination_item-textvar(--semi-transition_function-easeIn)翻页器页码文本-背景色-过渡曲线
    $transition_delay-pagination_item-textvar(--semi-transition_delay-none)翻页器页码文本-背景色-延迟时间
    $transform_scale-pagination_itemvar(--semi-transform_scale-none)翻页器item-放大
    $color-pagination-text-defaultvar(--semi-color-text-2)翻页器总页数文本颜色
    $color-pagination_item-text-defaultvar(--semi-color-text-0)翻页器 页码 文本颜色
    $color-pagination_item-icon-defaultvar(--semi-color-tertiary)翻页器 页码 图标颜色
    $color-pagination_item-text-hovervar(--semi-color-text-0)翻页器 页码 悬浮态文本颜色
    $color-pagination_item-bg-hovervar(--semi-color-fill-0)翻页器 页码 悬浮态背景颜色
    $color-pagination_item-text-activevar(--semi-color-text-0)翻页器 页码 按下态文字颜色
    $color-pagination_item-bg-activevar(--semi-color-fill-1)翻页器 页码 按下态背景颜色
    $color-pagination_item-text-disabledvar(--semi-color-disabled-text)翻页器 页码 禁用态文字颜色
    $color-pagination_item-icon-disabledvar(--semi-color-disabled-text)翻页器 页码 禁用态图标颜色
    $color-pagination_item-bg-disabledtransparent翻页器 页码 禁用态背景颜色
    $color-pagination_item-bg-selected-disabledvar(--semi-color-disabled-fill)翻页器 页码 选中禁用态背景颜色
    $color-pagination_item-text-selectedvar(--semi-color-primary)翻页器 页码 选中态文字颜色
    $color-pagination_item-bg-selectedvar(--semi-color-primary-light-default)翻页器 页码 选中态背景颜色
    $color-pagination_quickjump_text-disabledvar(--semi-color-disabled-text)翻页器 快速跳转禁用态文字颜色
    $color-pagination_item-border-defaulttransparent翻页器 页码 默认边框颜色
    $color-pagination_item-border-hovertransparent翻页器 页码 悬浮边框颜色
    $color-pagination_item-border-activetransparent翻页器 页码 激活边框颜色
    $color-pagination_item-border-selectedtransparent翻页器 页码 选中边框颜色
    $color-pagination_item-border-disabledtransparent翻页器 页码 禁用边框颜色
    $height-pagination_item32px翻页器 页码高度
    $width-pagination_item-minWidth32px翻页器 页码最小宽度
    $width-pagination_item_small-minWidth44px迷你翻页器 页码最小宽度
    $width-pagination_quickjump_input_width50px快速跳转输入框宽度
    $width-pagination_item_border0px翻页器 页码 默认边框宽度
    $spacing-pagination-padding0翻页器内边距
    $spacing-pagination_small-paddingY0迷你翻页器垂直内边距
    $spacing-pagination_small-paddingX0迷你翻页器水平内边距
    $spacing-pagination_item-marginLeft$spacing-extra-tight翻页器页码左侧外边距
    $spacing-pagination_item-marginRight$spacing-extra-tight翻页器页码右侧外边距
    $spacing-pagination_item_small-margin0迷你翻页器页码外边距
    $spacing-pagination_reset_list-paddingTop$spacing-extra-tight
    $spacing-pagination_reset_list-paddingBottom$spacing-extra-tight
    $spacing-pagination_quickjump_marginLeft24px快速跳转左侧外边距
    $spacing-pagination_quickjump_input_marginLeft4px快速跳转输入框左侧外边距
    $spacing-pagination_quickjump_input_marginRight4px快速跳转输入框右侧外边距
    $radius-pagination_itemvar(--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翻页器页码选中态字重