分页

用原生控件在页码或表格分页范围中切换。

本指南覆盖默认 Emotion 环境的 Material UI Core；扩展包与额外示例按清单单独标注。

使用场景与业务边界

Pagination 从 1 开始，TablePagination 从 0 开始；二者都不获取行数据或维护总数。

原生组成与范围

Pagination, PaginationItem, TablePagination, TablePaginationActions

保持 Material UI 原生组合与类型，不替换为 JGuang／Base UI／Radix 同名 API。示例条目不是额外组件。

原生安装与初始化

npm install @mui/material@9.4.0 @emotion/react@11.14.0 @emotion/styled@11.14.1

采用原生 npm 包与 Emotion，不提供虚构的 JGuang UI Registry 地址。将示例放在原生 ThemeProvider 内，按项目选择 CssBaseline 或 ScopedCssBaseline。先检查 React、现有 Provider、锁文件与 SSR 配置；不要覆盖用户文件或忽略 peer 冲突。本批实际验收 React 19.2.8；React 18 及以下须匹配 react-is。完整初始化规则见随附的双语 setup 文档。

关键原生参数

仅解释本指南选出的关键参数，不是平铺的通用 API。原生继承来源、slot 结构、可空值与泛型仍按固定源码保留。

可运行原生示例

下列机器键只选择示例入口，不会作为通用 variant 属性传入每个组件。原生示例 JSX 与数据保持上游原文；JGuang 编写的验收示例明确标注。

• 基础分页 · BasicPagination · 上游原生示例
• 描边分页 · PaginationOutlined · 上游原生示例
• 圆角分页 · PaginationRounded · 上游原生示例
• 分页尺寸 · PaginationSize · 上游原生示例
• 按钮配置 · PaginationButtons · 上游原生示例
• 自定义图标 · CustomIcons · 上游原生示例
• 分页范围 · PaginationRanges · 上游原生示例
• 受控分页 · PaginationControlled · 上游原生示例
• 原生分页 Hook · UsePagination · 上游原生示例
• 表格分页 · TablePaginationDemo · 上游原生示例

尚未支持的额外示例

这些条目仍保留在上游清单中，不静默跳过，也不展示为已完成预览。需要补充依赖／框架验收后再纳入可运行列表。

• 路由扩展 · PaginationLink: react-router

真实使用示例

固定版本的未修改原生示例；复制时同时保留所需的局部辅助文件。

import Pagination from '@mui/material/Pagination';
import Stack from '@mui/material/Stack';

export default function BasicPagination() {
  return (
    <Stack spacing={2}>
      <Pagination count={10} />
      <Pagination count={10} color="primary" />
      <Pagination count={10} color="secondary" />
      <Pagination count={10} disabled />
    </Stack>
  );
}

示例依赖边界

@mui/material/Pagination, @mui/material/Stack, @mui/material/PaginationItem, @mui/icons-material/ArrowBack, @mui/icons-material/ArrowForward, react, @mui/material/Typography, @mui/material/usePagination, @mui/material/styles, @mui/material/TablePagination

直接导入 Icons／System／Utils 的示例需要匹配 9.4.0 包。局部数据与辅助文件属于示例闭包，不是额外组件。远程图片和模拟操作不提供后端。

固定上游 API 元数据参考

以下表格保留上游元数据，不是重新推断的通用类型体系。条件泛型、继承属性与回调细节以以下源码声明为准。主题默认配置可能覆盖元数据默认值。

Pagination

import Pagination from '@mui/material/Pagination';
import { Pagination } from '@mui/material';

PaginationItem

import PaginationItem from '@mui/material/PaginationItem';
import { PaginationItem } from '@mui/material';

原生继承: ButtonBase. 父级与 DOM 属性未被伪造为本组件新属性。

TablePagination

import TablePagination from '@mui/material/TablePagination';
import { TablePagination } from '@mui/material';

原生继承: TableCell. 父级与 DOM 属性未被伪造为本组件新属性。

TablePaginationActions

import TablePaginationActions from '@mui/material/TablePaginationActions';
import { TablePaginationActions } from '@mui/material';

原生源码声明

声明与 import 从固定源码提取，不平铺联合类型或外部继承。英文注释／类型属于原始源码参考，不代表上游正文已全文翻译。共享类型仍位于原生包中。

vendor/src/Pagination/Pagination.d.ts

import * as React from 'react';

import { OverridableStringUnion } from '@mui/types';

import { SxProps } from '@mui/system';

import { Theme } from '../styles';

import { InternalStandardProps as StandardProps } from '../internal';

import { UsePaginationItem, UsePaginationProps } from '../usePagination/usePagination';

import { PaginationClasses } from './paginationClasses';

export interface PaginationRenderItemParams extends UsePaginationItem {
  color: PaginationProps['color'];
  shape: PaginationProps['shape'];
  size: PaginationProps['size'];
  variant: PaginationProps['variant'];
}

export interface PaginationPropsVariantOverrides {}

export interface PaginationPropsSizeOverrides {}

export interface PaginationPropsColorOverrides {}

export interface PaginationProps
  extends
    UsePaginationProps,
    StandardProps<React.HTMLAttributes<HTMLElement>, 'children' | 'onChange'> {
  /**
   * Override or extend the styles applied to the component.
   */
  classes?: Partial<PaginationClasses> | undefined;
  /**
   * The active color.
   * It supports both default and custom theme colors, which can be added as shown in the
   * [palette customization guide](https://mui.com/material-ui/customization/palette/#custom-colors).
   * @default 'standard'
   */
  color?:
    | OverridableStringUnion<'primary' | 'secondary' | 'standard', PaginationPropsColorOverrides>
    | undefined;
  /**
   * Accepts a function which returns a string value that provides a user-friendly name for the current page.
   * This is important for screen reader users.
   *
   * For localization purposes, you can use the provided [translations](https://mui.com/material-ui/guides/localization/).
   * @param {string} type The link or button type to format ('page' | 'first' | 'last' | 'next' | 'previous' | 'start-ellipsis' | 'end-ellipsis'). Defaults to 'page'.
   * @param {number | null} page The page number to format.
   * @param {boolean} selected If true, the current page is selected.
   * @returns {string}
   */
  getItemAriaLabel?:
    | ((
        type: UsePaginationItem['type'],
        page: UsePaginationItem['page'],
        selected: UsePaginationItem['selected'],
      ) => string)
    | undefined;

  /**
   * Render the item.
   * @param {PaginationRenderItemParams} params The props to spread on a PaginationItem.
   * @returns {ReactNode}
   * @default (item) => <PaginationItem {...item} />
   */
  renderItem?: ((params: PaginationRenderItemParams) => React.ReactNode) | undefined;
  /**
   * The shape of the pagination items.
   * @default 'circular'
   */
  shape?: 'circular' | 'rounded' | undefined;
  /**
   * The size of the component.
   * @default 'medium'
   */
  size?:
    OverridableStringUnion<'small' | 'medium' | 'large', PaginationPropsSizeOverrides> | undefined;
  /**
   * The system prop that allows defining system overrides as well as additional CSS styles.
   */
  sx?: SxProps<Theme> | undefined;
  /**
   * The variant to use.
   * @default 'text'
   */
  variant?:
    OverridableStringUnion<'text' | 'outlined', PaginationPropsVariantOverrides> | undefined;
}

export default function Pagination(props: PaginationProps): React.JSX.Element;

vendor/src/PaginationItem/PaginationItem.d.ts

import * as React from 'react';

import { OverridableStringUnion } from '@mui/types';

import { SxProps } from '@mui/system';

import { OverridableComponent, OverrideProps } from '../OverridableComponent';

import { Theme } from '../styles';

import { UsePaginationItem } from '../usePagination/usePagination';

import { PaginationItemClasses } from './paginationItemClasses';

import { CreateSlotsAndSlotProps, SlotProps } from '../utils/types';

export interface PaginationItemPropsVariantOverrides {}

export interface PaginationItemPropsSizeOverrides {}

export interface PaginationItemPropsColorOverrides {}

export interface PaginationItemFirstSlotPropsOverrides {}

export interface PaginationItemLastSlotPropsOverrides {}

export interface PaginationItemNextSlotPropsOverrides {}

export interface PaginationItemPreviousSlotPropsOverrides {}

export interface PaginationItemSlots {
  /**
   * The component that renders the first page slot.
   * @default FirstPageIcon
   */
  first: React.ElementType;
  /**
   * The component that renders the last page slot.
   * @default LastPageIcon
   */
  last: React.ElementType;
  /**
   * The component that renders the next page slot.
   * @default NavigateNextIcon
   */
  next: React.ElementType;
  /**
   * The component that renders the previous page slot.
   * @default NavigateBeforeIcon
   */
  previous: React.ElementType;
}

export type PaginationItemSlotsAndSlotProps = CreateSlotsAndSlotProps<
  PaginationItemSlots,
  {
    /**
     * Props forwarded to the first page slot.
     */
    first: SlotProps<
      React.ElementType<React.HTMLProps<HTMLElement>>,
      PaginationItemFirstSlotPropsOverrides,
      PaginationItemOwnerState
    >;
    /**
     * Props forwarded to the last page slot.
     */
    last: SlotProps<
      React.ElementType<React.HTMLProps<HTMLElement>>,
      PaginationItemLastSlotPropsOverrides,
      PaginationItemOwnerState
    >;
    /**
     * Props forwarded to the next page slot.
     */
    next: SlotProps<
      React.ElementType<React.HTMLProps<HTMLElement>>,
      PaginationItemNextSlotPropsOverrides,
      PaginationItemOwnerState
    >;
    /**
     * Props forwarded to the previous page slot.
     */
    previous: SlotProps<
      React.ElementType<React.HTMLProps<HTMLElement>>,
      PaginationItemPreviousSlotPropsOverrides,
      PaginationItemOwnerState
    >;
  }
>;

export interface PaginationItemOwnerState extends PaginationItemProps {}

export interface PaginationItemOwnProps extends PaginationItemSlotsAndSlotProps {
  /**
   * Override or extend the styles applied to the component.
   */
  classes?: Partial<PaginationItemClasses> | undefined;
  /**
   * The active color.
   * It supports both default and custom theme colors, which can be added as shown in the
   * [palette customization guide](https://mui.com/material-ui/customization/palette/#custom-colors).
   * @default 'standard'
   */
  color?:
    | OverridableStringUnion<
        'standard' | 'primary' | 'secondary',
        PaginationItemPropsColorOverrides
      >
    | undefined;
  /**
   * If `true`, the component is disabled.
   * @default false
   */
  disabled?: boolean | undefined;
  /**
   * Whether the custom component should render a native `<button>` element when
   * rendering a React component with the `component` or `slots` prop.
   */
  nativeButton?: boolean | undefined;
  /**
   * The current page number.
   */
  page?: React.ReactNode;
  /**
   * If `true` the pagination item is selected.
   * @default false
   */
  selected?: boolean | undefined;
  /**
   * The shape of the pagination item.
   * @default 'circular'
   */
  shape?: 'circular' | 'rounded' | undefined;
  /**
   * The size of the component.
   * @default 'medium'
   */
  size?:
    | OverridableStringUnion<'small' | 'medium' | 'large', PaginationItemPropsSizeOverrides>
    | undefined;
  /**
   * The system prop that allows defining system overrides as well as additional CSS styles.
   */
  sx?: SxProps<Theme> | undefined;
  /**
   * The type of pagination item.
   * @default 'page'
   */
  type?: UsePaginationItem['type'] | undefined;
  /**
   * The variant to use.
   * @default 'text'
   */
  variant?:
    OverridableStringUnion<'text' | 'outlined', PaginationItemPropsVariantOverrides> | undefined;
}

export interface PaginationItemTypeMap<
  AdditionalProps = {},
  RootComponent extends React.ElementType = 'div',
> {
  props: AdditionalProps & PaginationItemOwnProps;
  defaultComponent: RootComponent;
}

declare const PaginationItem: OverridableComponent<PaginationItemTypeMap>;

export type PaginationItemProps<
  RootComponent extends React.ElementType = PaginationItemTypeMap['defaultComponent'],
  AdditionalProps = {},
> = OverrideProps<PaginationItemTypeMap<AdditionalProps, RootComponent>, RootComponent> & {
  component?: React.ElementType | undefined;
};

vendor/src/TablePagination/TablePagination.d.ts

import * as React from 'react';

import { SxProps } from '@mui/system';

import { Theme } from '../styles';

import { OverridableComponent, OverrideProps } from '../OverridableComponent';

import {
  TablePaginationActionsProps,
  TablePaginationActionsSlots,
} from '../TablePaginationActions';

import { TableCellProps } from '../TableCell';

import { SelectProps } from '../Select';

import { TablePaginationClasses } from './tablePaginationClasses';

import { CreateSlotsAndSlotProps, SlotProps } from '../utils/types';

import { ToolbarProps } from '../Toolbar';

import { MenuItemProps } from '../MenuItem';

export interface LabelDisplayedRowsArgs {
  from: number;
  to: number;
  count: number;
  page: number;
}

export interface TablePaginationRootSlotPropsOverrides {}

export interface TablePaginationToolbarSlotPropsOverrides {}

export interface TablePaginationSpacerSlotPropsOverrides {}

export interface TablePaginationSelectLabelSlotPropsOverrides {}

export interface TablePaginationSelectSlotPropsOverrides {}

export interface TablePaginationMenuItemSlotPropsOverrides {}

export interface TablePaginationDisplayedRowsSlotPropsOverrides {}

export interface TablePaginationActionsSlotPropsOverrides {}

export interface TablePaginationSlots {
  /**
   * The component that renders the root slot.
   * [Follow this guide](https://mui.com/material-ui/api/table-cell/#props) to learn more about the requirements for this component.
   * @default TableCell
   */
  root: React.ElementType;
  /**
   * The component that renders the toolbar slot.
   * [Follow this guide](https://mui.com/material-ui/api/toolbar/#props) to learn more about the requirements for this component.
   * @default Toolbar
   */
  toolbar: React.ElementType;
  /**
   * The tag that renders the spacer slot.
   * @default 'div'
   */
  spacer: React.ElementType;
  /**
   * The tag that renders the selectLabel slot.
   * @default 'p'
   */
  selectLabel: React.ElementType;
  /**
   * The component that renders the select slot.
   * [Follow this guide](https://mui.com/material-ui/api/select/#props) to learn more about the requirements for this component.
   * @default Select
   */
  select: React.ElementType;
  /**
   * The component that renders the select slot.
   * [Follow this guide](https://mui.com/material-ui/api/menu-item/#props) to learn more about the requirements for this component.
   * @default MenuItem
   */
  menuItem: React.ElementType;
  /**
   * The tag that renders the displayedRows slot.
   * @default 'p'
   */
  displayedRows: React.ElementType;
  /**
   * The slots that passed to the actions slot.
   */
  actions: TablePaginationActionsSlots;
}

export type TablePaginationSlotsAndSlotProps = CreateSlotsAndSlotProps<
  TablePaginationSlots,
  {
    /**
     * Props forwarded to the root slot.
     * By default, the available props are based on the [TableCell](https://mui.com/material-ui/api/table-cell/#props) component.
     */
    root: SlotProps<
      React.ElementType<TableCellProps>,
      TablePaginationRootSlotPropsOverrides,
      TablePaginationOwnerState
    >;
    /**
     * Props forwarded to the toolbar slot.
     * By default, the available props are based on the [Toolbar](https://mui.com/material-ui/api/toolbar/#props) component.
     */
    toolbar: SlotProps<
      React.ElementType<ToolbarProps>,
      TablePaginationToolbarSlotPropsOverrides,
      TablePaginationOwnerState
    >;
    /**
     * Props forwarded to the spacer slot.
     * By default, the available props are based on the div element.
     */
    spacer: SlotProps<'div', TablePaginationSpacerSlotPropsOverrides, TablePaginationOwnerState>;
    /**
     * Props forwarded to the selectLabel slot.
     * By default, the available props are based on the paragraph element.
     */
    selectLabel: SlotProps<
      'p',
      TablePaginationSelectLabelSlotPropsOverrides,
      TablePaginationOwnerState
    >;
    /**
     * Props forwarded to the select slot.
     * By default, the available props are based on the [Select](https://mui.com/material-ui/api/select/#props) component.
     */
    select: Partial<SelectProps> & TablePaginationSelectSlotPropsOverrides;
    /**
     * Props forwarded to the menuItem slot.
     * By default, the available props are based on the [MenuItem](https://mui.com/material-ui/api/menu-item/#props) component.
     */
    menuItem: SlotProps<
      React.ElementType<MenuItemProps>,
      TablePaginationMenuItemSlotPropsOverrides,
      TablePaginationOwnerState
    >;
    /**
     * Props forwarded to the displayedRows slot.
     * By default, the available props are based on the paragraph element.
     */
    displayedRows: SlotProps<
      'p',
      TablePaginationDisplayedRowsSlotPropsOverrides,
      TablePaginationOwnerState
    >;
    /**
     * Props forwarded to the actions slot.
     */
    actions: TablePaginationActionsProps['slotProps'] & TablePaginationActionsSlotPropsOverrides;
  }
>;

export type TablePaginationBaseProps = Omit<TableCellProps, 'classes' | 'component' | 'children'>;

export interface TablePaginationOwnProps extends TablePaginationBaseProps {
  /**
   * The component used for displaying the actions.
   * Either a string to use a HTML element or a component.
   * @default TablePaginationActions
   */
  ActionsComponent?: React.ElementType<TablePaginationActionsProps> | undefined;
  /**
   * Override or extend the styles applied to the component.
   */
  classes?: Partial<TablePaginationClasses> | undefined;
  /**
   * The total number of rows.
   *
   * To enable server side pagination for an unknown number of items, provide -1.
   */
  count: number;
  /**
   * If `true`, the component is disabled.
   * @default false
   */
  disabled?: boolean | undefined;
  /**
   * Accepts a function which returns a string value that provides a user-friendly name for the current page.
   * This is important for screen reader users.
   *
   * For localization purposes, you can use the provided [translations](https://mui.com/material-ui/guides/localization/).
   * @param {string} type The link or button type to format ('first' | 'last' | 'next' | 'previous').
   * @returns {string}
   * @default function defaultGetAriaLabel(type) {
   *   return `Go to ${type} page`;
   * }
   */
  getItemAriaLabel?: ((type: 'first' | 'last' | 'next' | 'previous') => string) | undefined;
  /**
   * Customize the displayed rows label. Invoked with a `{ from, to, count, page }`
   * object.
   *
   * For localization purposes, you can use the provided [translations](https://mui.com/material-ui/guides/localization/).
   * @default function defaultLabelDisplayedRows({ from, to, count }) {
   *   return `${formatNumber(from)}–${formatNumber(to)} of ${count !== -1 ? formatNumber(count) : `more than ${formatNumber(to)}`}`;
   * }
   */
  labelDisplayedRows?: ((paginationInfo: LabelDisplayedRowsArgs) => React.ReactNode) | undefined;
  /**
   * Customize the rows per page label.
   *
   * For localization purposes, you can use the provided [translations](https://mui.com/material-ui/guides/localization/).
   * @default 'Rows per page:'
   */
  labelRowsPerPage?: React.ReactNode;
  /**
   * Callback fired when the page is changed.
   *
   * @param {React.MouseEvent<HTMLButtonElement> | null} event The event source of the callback.
   * @param {number} page The page selected.
   */
  onPageChange: (event: React.MouseEvent<HTMLButtonElement> | null, page: number) => void;
  /**
   * Callback fired when the number of rows per page is changed.
   *
   * @param {React.ChangeEvent<HTMLTextAreaElement | HTMLInputElement>} event The event source of the callback.
   */
  onRowsPerPageChange?:
    React.ChangeEventHandler<HTMLTextAreaElement | HTMLInputElement> | undefined;
  /**
   * The zero-based index of the current page.
   */
  page: number;
  /**
   * The number of rows per page.
   *
   * Set -1 to display all the rows.
   */
  rowsPerPage: number;
  /**
   * Customizes the options of the rows per page select field. If less than two options are
   * available, no select field will be displayed.
   * Use -1 for the value with a custom label to show all the rows.
   * @default [10, 25, 50, 100]
   */
  rowsPerPageOptions?: ReadonlyArray<number | { value: number; label: string }> | undefined;
  /**
   * If `true`, show the first-page button.
   * @default false
   */
  showFirstButton?: boolean | undefined;
  /**
   * If `true`, show the last-page button.
   * @default false
   */
  showLastButton?: boolean | undefined;
  /**
   * The system prop that allows defining system overrides as well as additional CSS styles.
   */
  sx?: SxProps<Theme> | undefined;
}

export interface TablePaginationOwnerState extends TablePaginationOwnProps {}

export interface TablePaginationTypeMap<AdditionalProps, RootComponent extends React.ElementType> {
  props: AdditionalProps & TablePaginationOwnProps & TablePaginationSlotsAndSlotProps;
  defaultComponent: RootComponent;
}

declare const TablePagination: OverridableComponent<
  TablePaginationTypeMap<{}, React.JSXElementConstructor<TablePaginationBaseProps>>
>;

export type TablePaginationProps<
  RootComponent extends React.ElementType = React.JSXElementConstructor<TablePaginationBaseProps>,
  AdditionalProps = {},
> = OverrideProps<TablePaginationTypeMap<AdditionalProps, RootComponent>, RootComponent> & {
  component?: React.ElementType | undefined;
};

vendor/src/TablePaginationActions/TablePaginationActions.d.ts

import * as React from 'react';

import { IconButtonProps } from '../IconButton/IconButton';

import { SvgIconProps } from '../SvgIcon';

export interface TablePaginationActionsProps extends React.HTMLAttributes<HTMLDivElement> {
  /**
   * Override or extend the styles applied to the component.
   */
  classes?: {} | undefined;
  className?: string | undefined;
  count: number;
  /**
   * If `true`, the component is disabled.
   * @default false
   */
  disabled?: boolean | undefined;
  /**
   * Accepts a function which returns a string value that provides a user-friendly name for the current page.
   * This is important for screen reader users.
   *
   * For localization purposes, you can use the provided [translations](https://mui.com/material-ui/guides/localization/).
   * @param {string} type The link or button type to format ('first' | 'last' | 'next' | 'previous').
   * @returns {string}
   */
  getItemAriaLabel: (type: 'first' | 'last' | 'next' | 'previous') => string;
  onPageChange: (event: React.MouseEvent<HTMLButtonElement> | null, page: number) => void;
  page: number;
  rowsPerPage: number;
  showFirstButton: boolean;
  showLastButton: boolean;
  slotProps?:
    | {
        firstButton?: Partial<IconButtonProps> | undefined;
        lastButton?: Partial<IconButtonProps> | undefined;
        nextButton?: Partial<IconButtonProps> | undefined;
        previousButton?: Partial<IconButtonProps> | undefined;
        firstButtonIcon?: Partial<SvgIconProps> | undefined;
        lastButtonIcon?: Partial<SvgIconProps> | undefined;
        nextButtonIcon?: Partial<SvgIconProps> | undefined;
        previousButtonIcon?: Partial<SvgIconProps> | undefined;
      }
    | undefined;
  slots?: TablePaginationActionsSlots | undefined;
}

export interface TablePaginationActionsSlots {
  /**
   * The component that renders the first button.
   * @default IconButton
   */
  firstButton?: React.ElementType | undefined;
  /**
   * The component that renders the last button.
   * @default IconButton
   */
  lastButton?: React.ElementType | undefined;
  /**
   * The component that renders the next button.
   * @default IconButton
   */
  nextButton?: React.ElementType | undefined;
  /**
   * The component that renders the previous button.
   * @default IconButton
   */
  previousButton?: React.ElementType | undefined;
  /**
   * The component that renders the first button icon.
   * @default FirstPageIcon
   */
  firstButtonIcon?: React.ElementType | undefined;
  /**
   * The component that renders the last button icon.
   * @default LastPageIcon
   */
  lastButtonIcon?: React.ElementType | undefined;
  /**
   * The component that renders the next button icon.
   * @default KeyboardArrowRight
   */
  nextButtonIcon?: React.ElementType | undefined;
  /**
   * The component that renders the previous button icon.
   * @default KeyboardArrowLeft
   */
  previousButtonIcon?: React.ElementType | undefined;
}

declare const TablePaginationActions: React.JSXElementConstructor<TablePaginationActionsProps>;

安装后验收

执行严格类型检查、生产构建和实际交互。检查键盘标签／焦点、原生支持的禁用／错误／只读语义、深浅色、窄屏和减少动画。按真实宿主数据检查回调，不把复制提示词当作安装完成。初始化工具还需检查服务端 HTML 与无告警水合。

来源与许可

https://github.com/mui/material-ui/tree/809a7717b4c050ba3f69b75300689f07c050a16e

MIT · @mui/material@9.4.0. 保留上游原始内容与许可证。上游完整原文保留于 vendor/docs，不标为全文中文化。