翻页器 - Semi Design Next

代码演示

如何引入

import { Pagination } from '@fibrous/semi-ui-react';

基本

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

代码

import { Pagination } from '@fibrous/semi-ui-react';

export default function PaginationDemo() {
    return (
        <div>
            <Pagination total={30} style={{ marginBottom: 12 }} />
            <Pagination total={80} style={{ marginBottom: 12 }} />
            <Pagination total={200} style={{ marginBottom: 12 }} />
            <Pagination total={80} pageSize={30} style={{ marginBottom: 12 }} />
        </div>
    );
}

禁用

通过 disabled 设置禁用

代码

import { Pagination } from '@fibrous/semi-ui-react';

export default function PaginationDemo() {
    return <Pagination total={30} disabled style={{ marginBottom: 12 }} />;
}

总页数显示

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

总页数：8

总页数：20

代码

import { Pagination } from '@fibrous/semi-ui-react';

export default function PaginationDemo() {
    return (
        <div>
            <Pagination total={80} showTotal style={{ marginBottom: 12 }} />
            <Pagination total={200} showTotal style={{ marginBottom: 12 }} />
        </div>
    );
}

指定当前页码

可以通过 defaultCurrentPage 指定当前激活的页码

总页数：8

代码

import { Pagination } from '@fibrous/semi-ui-react';

export default function PaginationDemo() {
    return (
        <div>
            <Pagination total={80} showTotal defaultCurrentPage={3} />
        </div>
    );
}

每页容量切换

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

每页条数：10

每页条数：10

代码

import { Pagination } from '@fibrous/semi-ui-react';

export default function PaginationDemo() {
    return (
        <div>
            <Pagination total={80} showSizeChanger style={{ marginBottom: 12 }} />
            <Pagination total={300} showSizeChanger />
        </div>
    );
}

快速跳转至某页

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

跳至
页

跳至
页

代码

import { Pagination } from '@fibrous/semi-ui-react';

export default function PaginationDemo() {
    return (
        <div>
            <Pagination total={80} showQuickJumper style={{ marginBottom: 12 }} />
            <Pagination total={300} showQuickJumper />
        </div>
    );
}

页码受控

传入 currentPage 后，分页器即为受控组件，一般配合 onPageChange 使用。当前激活页码完全取决于传入的 currentPage 的值

代码

import { useState } from 'react';
import { Pagination } from '@fibrous/semi-ui-react';

export default function PaginationDemo() {
    const [page, setPage] = useState(3);
    function onPageChange(currentPage: number) {
        setPage(currentPage);
    }
    return <Pagination total={200} currentPage={page} onPageChange={onPageChange} />;
}

预设每页容量可选值

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

每页条数：50

每页条数：10

代码

import { Pagination } from '@fibrous/semi-ui-react';

export default function PaginationDemo() {
    return (
        <div>
            <Pagination total={300} showSizeChanger style={{ marginBottom: 12 }} pageSizeOpts={[50, 80, 90, 200]} />
            <Pagination total={300} showSizeChanger pageSizeOpts={[10, 20, 50, 200]} />
        </div>
    );
}

迷你版本

size 设置为 small

代码

import { Pagination } from '@fibrous/semi-ui-react';

export default function PaginationDemo() {
    return <Pagination total={90} size="small" />;
}

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

代码

import { Pagination } from '@fibrous/semi-ui-react';

export default function PaginationDemo() {
    return <Pagination total={90} size="small" hoverShowPageSelect />;
}

API 参考

Props

属性	说明	类型	默认值
className	根元素 `ul` 的类名。	`string`	`""`
currentPage	当前页码。传入后分页器受控，页码完全由该属性决定；不传（undefined）时由组件自己管理。	`number`	-
defaultCurrentPage	非受控时的初始页码。	`number`	`1`
disabled	是否禁用。禁用时翻页按钮、页码、每页条数选择器与快速跳转均不可用。	`boolean`	`false`
hideOnSinglePage	总页数小于 2 时是否隐藏分页器；每页条数选择器显示时不生效。	`boolean`	`false`
hoverShowPageSelect	仅 `size` 为 `small` 时生效：悬停或聚焦页码文字时打开页码列表。	`boolean`	-
nextText	替换下一页按钮的内容，命名规则同 `prevText`。	`React.ReactNode`	-
onChange	页码或每页条数变化时的回调，参数为页码与每页条数。	`Type`	-
onPageChange	页码变化时的回调，参数为新的页码。	`Type`	-
onPageSizeChange	每页条数变化时的回调，参数为新的每页条数。	`Type`	-
pageSize	每页条数，未传时取 `pageSizeOpts` 的第一项。非严格受控：每页条数选择器的选择保留在组件内部，只有该属性变为与当前不同的值时才会覆盖它，并回到第 1 页（受控时回到 `currentPage`）；在 `onChange` 中回写该属性不会重置页码。	`number`	`null`
pageSizeOpts	每页条数选择器的可选值；当前每页条数不在其中时按大小插入选项。	`Type`	`[10, 20, 40, 100]`
popoverPosition	省略页码浮层与每页条数下拉的位置。未传时每页条数下拉为 `bottomLeft`（RTL 下 `bottomRight`），省略页码浮层使用 Popover 的默认位置 `bottom`；`size` 为 `small` 时不使用。	`PopoverPosition`	-
preventPageChangeOnPageSizeChange	切换每页条数时保持当前页码不变且不触发 `onPageChange`，新的页码由使用方在 `onPageSizeChange` 中决定。	`boolean`	`false`
prevText	替换上一页按钮的内容。纯文本时按钮以该文字命名，其他内容（图标、元素）仍使用语言包的名称；为空时保留默认图标与语言包名称。	`React.ReactNode`	-
ref	根元素 `ul` 的 ref，两种尺寸一致。	`Type`	-
showQuickJumper	是否显示快速跳转输入框，总页数小于 2 时禁用。	`boolean`	`false`
showSizeChanger	是否显示每页条数选择器，`size` 为 `small` 时不生效。开启后 `hideOnSinglePage` 不再生效。	`boolean`	`false`
showTotal	是否显示总页数，`size` 为 `small` 时不显示。	`boolean`	`false`
size	尺寸，可选 `default` 或 `small`。	`'small' \| 'default'`	`"default"`
style	根元素 `ul` 的内联样式。	`React.CSSProperties`	-
total	总条数。总条数变化时，非受控的分页器回到第 1 页；受控时页码以 `currentPage` 为准。	`number`	`1`

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-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	翻页器页码选中态字重