企业官网建设流程全解析

• 前端
• UI组件

分页导航（Pagination）用于辅助长列表只加载部分数据，用户可以快速切换到指定的数据页。在 rsuite 中，size属性用于调整分页组件的整体尺寸，可选值为'xs'、'sm'、'md'、'lg'。本文将围绕 docs/pages/components/pagination/fragments/size.md 文档中的示例，结合 rsuite 源码（src/Pagination）与样式定义，讲解如何在不同页面密度和交互场景下正确使用四种尺寸，并解释尺寸属性在组件树中的传递机制与样式生效原理。

一、size 属性：一行代码适配不同页面密度

rsuite 的分页组件支持四种尺寸，通过size属性即可切换。文档 size.md 中的示例展示了在同一个组件上以xs、sm、md、lg分别渲染的效果：

import { Pagination } from 'rsuite'; const App = () => { const [activePage, setActivePage] = React.useState(5); const pageProps = { prev: true, last: true, next: true, first: true, total: 100, limit: 10, activePage, onChangePage: setActivePage }; return ( <> <Pagination {...pageProps} size="xs" /> <Divider /> <Pagination {...pageProps} size="sm" /> <Divider /> <Pagination {...pageProps} size="md" /> <Divider /> <Pagination {...pageProps} size="lg" /> </> ); }; ReactDOM.render(<App />, document.getElementById('root'));

这段示例同时开启了prev、next、first、last四个导航按钮，配合total={100}与limit={10}，rsuite 会自动计算出 10 个页码。activePage通过useState维护，onChangePage负责在用户点击页码时同步更新当前页。

四种尺寸的适用场景可以概括为：

• xs：紧凑型，适合工具栏、表格底部等空间受限的位置，按钮最小宽度仅 24px；
• sm：默认尺寸（size属性缺省时的取值），适用于大多数常规列表场景；
• md：中等尺寸，按钮最小宽度 36px，交互面积更大，适合鼠标操作密集的页面；
• lg：大尺寸，按钮最小宽度 42px，适合触屏设备或需要突出分页导航的界面。

二、四种尺寸的样式差异与实现原理

1. 尺寸如何映射为 CSS 样式

size属性最终会以data-size属性的形式写入组件的根节点，样式系统据此选择对应的 CSS 规则。在 Pagination.tsx 中可以看到这一关键逻辑：

<Box as={as} ref={ref} className={classes}>&[data-size='lg'] { .rs-pagination-btn { min-width: 42px; } } &[data-size='md'] { .rs-pagination-btn { min-width: 36px; } } &[data-size='sm'] { .rs-pagination-btn { min-width: 30px; } } &[data-size='xs'] { .rs-pagination-btn { min-width: 24px; } }

值得注意的是，这四种尺寸并非简单的线性缩放：md的按钮最小宽度（36px）大于sm（30px），但两者的字体大小相同。这一细节在 _pagination-group.scss 中有明确依据：

--rs-pagination-font-size-xs: var(--rs-font-size-xs); --rs-pagination-font-size-sm: var(--rs-font-size-sm); --rs-pagination-font-size-md: var(--rs-font-size-sm); --rs-pagination-font-size-lg: var(--rs-font-size-md);

即md与sm共用sm级别的字号，lg使用md级别的字号，尺寸的差异主要体现在按钮内边距与最小宽度上。该样式文件还通过循环为每种data-size应用对应的font-size：

$sizes: (xs, sm, md, lg); @each $size in $sizes { &[data-size='#{$size}'] { ... font-size: var(--rs-pagination-font-size-#{$size}); } }

2. 测试用例印证尺寸行为

仓库中的样式测试 PaginationGroup.styles.spec.tsx 精确验证了各尺寸对应的字体大小：

const FONT_SIZES: Record<NonNullable<PaginationGroupProps['size']>, string> = { xs: '12px', sm: '14px', md: '14px', lg: '16px' };

测试对xs、sm、md、lg逐一渲染layout={['total', 'skip']}的分页组件，断言 "Total Rows:" 与 "Go to" 文本的font-size与上表一致。这再次印证：sm与md字号相同，尺寸差异主要体现在按钮宽度与间距上。

三、size 属性在组件树中的传递链路

rsuite 的分页组件实际由两层构成：对外暴露的PaginationGroup（组件名即Pagination，默认classPrefix为pagination-group）与内部渲染页码按钮的Pagination。

1. 从 PaginationGroup 到 Pagination

在 PaginationGroup.tsx 中，size被同时应用到两个层面：

<Box as={as} ref={ref} className={classes}>case 'pager': return ( <Pagination key={onlyKey} size={size} prev={prev} next={next} first={first} last={last} maxButtons={maxButtons} pages={pages} disabled={disabled} onSelect={onChangePage as any} activePage={activePage} {...rest} /> );

此外，skip（快速跳转输入框）和limit（每页条数选择器）等布局元素同样接收size，从而保证整个分页区域的视觉尺寸保持一致。

2. 从 Pagination 到 PaginationButton

内部的Pagination组件在渲染每个页码按钮时，会把size作为PaginationButton的 prop 传入（Pagination.tsx）：

return ( <PaginationButton aria-label={title} title={title} {...itemRest} {...linkProps} key={`${key}-${eventKey}`} eventKey={eventKey} as={linkAs} size={size} disabled={disabledButton} onSelect={disabledButton ? undefined : onSelect} /> );

PaginationButton内部基于 rsuite 的Button组件渲染（PaginationButton.tsx），因此四种尺寸的按钮外观与 rsuite 按钮体系的尺寸规范保持一致。测试 PaginationGroup.spec.tsx 也验证了根节点上会渲染出data-size="lg"属性：

it('Should apply size prop to all components', () => { render(<PaginationGroup layout={['limit', 'pager', 'skip']} total={100} size="lg" />); expect(container.firstChild).to.have.attr('data-size', 'lg'); });

3. 尺寸在布局元素间的联动

当使用layout属性组合total、limit、skip等元素时，size会同步作用于这些元素。例如官方 Storybook 示例 Pagination.stories.tsx 展示了三种典型组合：

// 显示总条数 <Pagination total={100} limit={10} size="xs" layout={['total', '|', 'pager']} /> // 显示每页条数选择器 <Pagination total={100} limit={10} size="xs" limitOptions={[30, 50, 100]} limit={30} layout={['limit', '|', 'pager']} /> // 显示快速跳转输入框 <Pagination total={100} limit={10} size="xs" layout={['pager', '|', 'skip']} />

这意味着当你切换size时，不仅是页码按钮，总条数文本、跳转输入框、每页条数下拉框的字体与内边距都会同步变化，视觉上保持统一的节奏。

四、与 size 配合使用的关键属性

为了让size的示例真正可运行，还需要理解文档 index.md 中 Props 表格里的几个核心属性：

从源码看，size的默认值为'sm'（Pagination.tsx），activePage默认值为1，limit默认值为30，layout默认值为['pager']，limitOptions默认值为[30, 50, 100]（PaginationGroup.tsx）。在 size.md 示例中显式设置了limit={10}，因此 100 条数据会被划分为 10 页，默认停留在第 5 页。

五、尺寸选择与实战建议

1. 空间敏感的嵌入场景用xs：例如表格底部分页栏、弹窗内的数据列表，24px 的按钮最小宽度能让分页在有限宽度内完整展示。
2. 常规页面使用默认sm或md：二者字号一致，md通过更大的按钮宽度提升了点击命中率，适合老年用户或触屏设备场景。
3. 触屏或展示型页面用lg：42px 的按钮最小宽度符合触屏点击目标尺寸规范，也适合作为页面底部的独立分页区。
4. 组合layout时保持尺寸统一：启用total、limit、skip后，size会联动控制这些元素，建议在整站中为分页统一指定一种尺寸，保持视觉一致性。
5. 受控状态不要遗漏：示例中activePage与onChangePage成对出现（onChangePage: setActivePage），这是分页组件正常工作的基本要求；若引入路由，还可通过linkAs与linkProps将页码渲染为路由链接，实现 URL 与页码的同步。

结语

size属性虽然只有xs、sm、md、lg四个取值，但它在 rsuite 分页组件中承担着从根节点data-size到页码按钮、再到total/limit/skip各布局元素的全局尺寸控制职责。理解其样式映射（styles/index.scss）与传递链路（PaginationGroup.tsx → Pagination.tsx → PaginationButton.tsx），即可在实际项目中灵活适配不同页面密度与交互场景。

• 前端
• UI组件