Pagination

基础导航

基于 Bootstrap 5 的分页组件，用于将大量内容拆分到多个页面并提供跳转导航，支持图标链接、激活/禁用状态、尺寸调整、对齐方式与无障碍标签

Component Demo

Basic usage and examples of the Pagination component

基础示例

Pagination 渲染 `nav` + `ul.pagination` 结构，每个条目由 PaginationItem（`li.page-item`）与 PaginationLink（`a.page-link`）组合而成，方便屏幕阅读器播报可用链接数量

图标链接

使用图标或符号代替文字时，应为链接提供 `aria-label`，并为装饰性图标设置 `aria-hidden="true"`

激活状态

PaginationItem 的 active 渲染 `active` 类并设置 `aria-current="page"`；PaginationLink 的 active 将链接替换为不可交互的 `span`

禁用状态

PaginationItem 的 disabled 渲染 `disabled` 类并设置 `aria-disabled="true"`；PaginationLink 的 disabled 默认将链接替换为不可聚焦的 `span`，避免键盘与鼠标误操作

尺寸

size 属性分别渲染 `pagination-lg` 与 `pagination-sm` 类，提供更大或更小的分页尺寸

对齐

align 对应 flexbox 工具类 `justify-content-center`/`justify-content-end`，也可通过 listProps 传入任意 `justify-content-*` 类实现更多对齐方式

交互示例

通过 state 控制 active 与 disabled 属性即可实现受控分页，当前页：1 / 5

API Documentation

Complete API reference for the Pagination component

Props

Pagination

属性名	类型	默认值	描述
`align`	`PaginationAlign`	-	对齐方式，`center` 渲染 `justify-content-center`，`end` 渲染 `justify-content-end` flex 工具类
`as`	`ElementType`	`'nav'`	根元素标签，默认渲染 `nav` 并自动设置无障碍标签
`label`	`string`	`'pagination'`	根元素的 `aria-label` 无障碍标签，用于描述分页导航的用途
`listAs`	`ElementType`	`'ul'`	列表容器元素标签，对应渲染 `pagination` 类的元素
`listProps`	`HTMLAttributes<HTMLElement>`	-	透传给列表容器（默认 `ul`）的原生属性
`size`	`PaginationSize`	-	分页尺寸，`lg`/`sm` 分别渲染 `pagination-lg`/`pagination-sm` 类

PaginationItem

属性名	类型	默认值	描述
`active`	`boolean`	`false`	激活状态，渲染 `active` 类并设置 `aria-current="page"`
`as`	`ElementType`	`'li'`	渲染的元素标签
`disabled`	`boolean`	`false`	禁用状态，渲染 `disabled` 类并设置 `aria-disabled="true"`

PaginationLink

属性名	类型	默认值	描述
`active`	`boolean`	`false`	激活状态，渲染为不可交互的 `span` 以替换链接元素
`as`	`ElementType`	`'a'`	渲染的元素标签，激活、禁用或未设置 `href` 时默认渲染为 `span`
`disabled`	`boolean`	`false`	禁用状态，默认渲染为 `span`；显式 `as="a"` 时同时设置 `tabIndex={-1}` 与 `aria-disabled="true"`
`href`	`string`	-	链接地址，设置后渲染为 `a` 标签

Common Props

属性名	类型	默认值	描述
`children`	`ReactNode`	-	分页内容
`className`	`string`	-	自定义类名
`...rest`	`HTMLAttributes`	-	透传原生元素属性（如 `onClick`、`style` 等）

Type Definitions

PaginationAlign

分页对齐方式类型

export type PaginationAlign = 'center' | 'end';

PaginationItemProps

分页条目组件属性接口

export interface PaginationItemProps extends HTMLAttributes<HTMLElement> {
  active?: boolean;
  as?: ElementType;
  children?: ReactNode;
  className?: string;
  disabled?: boolean;
}

PaginationLinkProps

分页链接组件属性接口

export interface PaginationLinkProps extends HTMLAttributes<HTMLElement> {
  active?: boolean;
  as?: ElementType;
  children?: ReactNode;
  className?: string;
  disabled?: boolean;
  href?: string;
}

PaginationProps

分页容器组件属性接口

export interface PaginationProps extends HTMLAttributes<HTMLElement> {
  align?: PaginationAlign;
  as?: ElementType;
  children?: ReactNode;
  className?: string;
  label?: string;
  listAs?: ElementType;
  listProps?: HTMLAttributes<HTMLElement>;
  size?: PaginationSize;
}

PaginationSize

分页尺寸类型

export type PaginationSize = 'lg' | 'sm';