For AI agents: the complete documentation index is available at https://ifhover.github.io/leaf-ui/llms.txt, the full documentation bundle is available at https://ifhover.github.io/leaf-ui/llms-full.txt, and this page is available as Markdown at https://ifhover.github.io/leaf-ui/components/pagination.md.

Pagination 分页

按页浏览较多的数据。

基础用法

total 是完整结果的总条数,而不是当前页条数。页码从 1 开始,非受控用法由组件管理当前页。

basic.tsx
import { Pagination } from '@ifhover/leaf-ui';

export function PaginationBasic() {
  return <Pagination total={50} />;
}

越界页码会限制到有效范围。total={0} 时仍显示第 1 页,前后翻页按钮均禁用。

示例

按钮样式

通过 variant 选择描边或无边框的分页按钮。

描边(默认)
无边框
variants.tsx
import { Flex, Grid, Pagination, Text } from '@ifhover/leaf-ui';

export function PaginationVariants() {
  return (
    <Grid columns={1} gap={16}>
      <Flex direction="column" gap={8}>
        <Text tone="muted">描边(默认)</Text>
        <Pagination aria-label="描边分页" total={30} defaultCurrent={2} />
      </Flex>
      <Flex direction="column" gap={8}>
        <Text tone="muted">无边框</Text>
        <Pagination aria-label="无边框分页" total={30} defaultCurrent={2} variant="ghost" />
      </Flex>
    </Grid>
  );
}

不同尺寸

通过 size 设置分页按钮尺寸。

小
中(默认)
大
sizes.tsx
import { Flex, Grid, Pagination, Text } from '@ifhover/leaf-ui';

export function PaginationSizes() {
  return (
    <Grid columns={1} gap={16}>
      <Flex direction="column" gap={8}>
        <Text tone="muted">小</Text>
        <Pagination aria-label="小尺寸分页" total={30} defaultCurrent={2} size="sm" />
      </Flex>
      <Flex direction="column" gap={8}>
        <Text tone="muted">中(默认)</Text>
        <Pagination aria-label="中尺寸分页" total={30} defaultCurrent={2} size="md" />
      </Flex>
      <Flex direction="column" gap={8}>
        <Text tone="muted">大</Text>
        <Pagination aria-label="大尺寸分页" total={30} defaultCurrent={2} size="lg" />
      </Flex>
    </Grid>
  );
}

数据控制

加载远程数据时,同时控制 current 和 pageSize,在 onChange 中一起更新。数据请求由应用发起;下面用当前页和数据范围展示状态变化。

第 1 页,每页 10 条
controlled.tsx
import { Flex, Pagination, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';

export function PaginationControlled() {
  const [pagination, setPagination] = useState({ current: 1, pageSize: 10 });

  return (
    <Flex direction="column" gap={16}>
      <Pagination
        total={240}
        {...pagination}
        showTotal={(total, [start, end]) => `${start}-${end} / ${total} 条`}
        showSizeChanger
        showQuickJumper
        onChange={(current, pageSize) => setPagination({ current, pageSize })}
      />
      <Text tone="muted" role="status">
        第 {pagination.current} 页,每页 {pagination.pageSize} 条
      </Text>
    </Flex>
  );
}

改变每页条数会尽量保留当前数据位置:每页 10 条的第 3 页切换到每页 20 条,会进入第 2 页。外部属性变化不会额外触发 onChange。

简洁模式

设置 simple,只显示当前页和前后翻页操作。

simple.tsx
import { Pagination } from '@ifhover/leaf-ui';

export function PaginationSimple() {
  return <Pagination total={240} defaultCurrent={3} simple />;
}

禁用状态

通过 disabled 禁止切换分页。

states.tsx
import { Pagination } from '@ifhover/leaf-ui';

export function PaginationStates() {
  return <Pagination total={50} defaultCurrent={2} disabled />;
}

API

Pagination API

配置总条目数、当前页、每页数量和分页交互。

属性类型默认值说明
totalnumber必填数据总条数
currentnumber—受控页码,从 1 开始
defaultCurrentnumber1非受控初始页码
pageSizenumber—受控每页条数
defaultPageSizenumber10非受控初始每页条数
onChange(page: number, pageSize: number) => void—页码或条数实际变化时调用一次,同时返回两者
showSizeChangerbooleanfalse展示每页条数选择器
pageSizeOptionsreadonly number[][10, 20, 50, 100]可选每页条数;自动包含当前条数,忽略无效值并去重
showQuickJumperbooleanfalse回车或离开分页区域时跳转;点击其他分页控件时以该操作为准
showTotalboolean | ((total: number, range: readonly [number, number]) => ReactNode)falsetrue 展示默认统计,也可传入函数自定义;range 为当前页首末条目的序号
simplebooleanfalse只展示前后翻页和当前页 / 总页数
disabledbooleanfalse禁用交互。
hideOnSinglePagebooleanfalse总页数不足两页时隐藏
size'sm' | 'md' | 'lg''md'页码按钮、条数选择器和跳转输入框的尺寸
variant'outline' | 'ghost''outline'按钮样式:描边 / 无边框

组件同时支持 aria-label、className、style 等原生 <nav> 属性。