rsuite Button 组件详解：外观、尺寸、颜色、状态控制与源码级实现

• 前端
• UI组件

本篇技术指南围绕 rsuite 的 Button 按钮组件展开，覆盖外观（appearance）、尺寸（size）、颜色（color）、图标、块级布局、禁用/激活/加载与可切换状态等全部核心用法，并结合 Button 组件源码 与 样式变量定义 深入剖析其状态渲染、受控切换与类名体系，帮助你在项目中快速、规范地使用 rsuite 按钮，并理解其底层实现机制。

获取组件

Button是 rsuite 中最基础的组件元素，可以快速创建一个带样式的按钮。安装后通过如下方式引入：

import { Button } from 'rsuite'; const App = () => <Button>Default</Button>; ReactDOM.render(<App />, document.getElementById('root'));

完整的中文文档见 Button 按钮。

外观：appearance 属性

appearance属性设置按钮样式，默认值为'default'，选项包括：default、primary、link、subtle、ghost。其 TypeScript 定义（见 appearance 类型说明）为：

type Appearance = 'default' | 'primary' | 'link' | 'subtle' | 'ghost';

五种外观的完整示例：

import { Button, ButtonToolbar } from 'rsuite'; const App = () => ( <ButtonToolbar> <Button appearance="default">Default</Button> <Button appearance="primary">Primary</Button> <Button appearance="link">Link</Button> <Button appearance="subtle">Subtle</Button> <Button appearance="ghost">Ghost</Button> </ButtonToolbar> ); ReactDOM.render(<App />, document.getElementById('root'));

对应演示文件为 appearance.md。

按钮尺寸：size 属性

size属性设置按钮尺寸，默认值为'md'，选项包括：lg、md、sm、xs：

import { Button, ButtonToolbar } from 'rsuite'; const App = () => ( <ButtonToolbar> <Button size="lg">Large</Button> <Button size="md">Medium</Button> <Button size="sm">Small</Button> <Button size="xs">Xsmall</Button> </ButtonToolbar> ); ReactDOM.render(<App />, document.getElementById('root'));

对应演示文件为 size.md。

从源码结构看，尺寸并非简单的类名切换，而是由 CSS 变量驱动的：Button.tsx 在根元素上写入data-size={size}属性，index.scss 根据该属性应用不同的 CSS 变量组合。_variables.scss 中定义了各档位的实际尺寸：

同时字号、行高、水平/垂直内边距也随尺寸联动变化，因此只需设置一个size值即可整体缩放按钮，_mixin.scss 中的button-size-*mixin 正是负责把一整套尺寸变量注入对应状态。

彩色按钮：color 属性

color属性设置按钮配色，选项包括：red、orange、yellow、green、cyan、blue、violet。其 TypeScript 定义（见 color 类型说明）为：

type Color = 'red' | 'orange' | 'yellow' | 'green' | 'cyan' | 'blue' | 'violet';

彩色按钮通常需要配合appearance使用，官方演示中分别展示了primary、subtle、ghost三种外观下的七色按钮（color.md）：

import { Button, ButtonToolbar } from 'rsuite'; const App = () => ( <> <ButtonToolbar> <Button color="red" appearance="primary">Red</Button> <Button color="orange" appearance="primary">Orange</Button> <Button color="yellow" appearance="primary">Yellow</Button> <Button color="green" appearance="primary">Green</Button> <Button color="cyan" appearance="primary">Cyan</Button> <Button color="blue" appearance="primary">Blue</Button> <Button color="violet" appearance="primary">Violet</Button> </ButtonToolbar> <ButtonToolbar> <Button color="red" appearance="subtle">Red</Button> {/* ... orange / yellow / green / cyan / blue / violet 同理 ... */} </ButtonToolbar> <ButtonToolbar style={{ background: '#000', padding: 10 }}> <Button color="red" appearance="ghost">Red</Button> {/* ... 其余颜色同理，ghost 建议放在深色背景上 ... */} </ButtonToolbar> </> ); ReactDOM.render(<App />, document.getElementById('root'));

在实现层面，color会以data-color={color}的形式落到 DOM 上（Button.tsx），SCSS 层据此为不同颜色、不同外观组合生成对应的前景色/背景色变量，这也是为什么ghost外观适合放在深色背景（演示中即包裹在黑色背景的ButtonToolbar内）的原因。

图标：startIcon 与 endIcon

通过startIcon在文字之前、endIcon在文字之后放置图标，图标可以是@rsuite/icons或第三方图标库的组件：

图标在文字之前（with-icon-before.md）：

import { Button, ButtonToolbar } from 'rsuite'; import AddOutlineIcon from '@rsuite/icons/AddOutline'; import GearIcon from '@rsuite/icons/Gear'; const App = () => ( <ButtonToolbar> <Button startIcon={<AddOutlineIcon />}> Add </Button> <Button startIcon={<GearIcon />}> Settings </Button> </ButtonToolbar> ); ReactDOM.render(<App />, document.getElementById('root'));

图标在文字之后（with-icon-after.md）：

import { Button, ButtonToolbar } from 'rsuite'; import { FaExternalLinkSquareAlt } from 'react-icons/fa'; import PageEndIcon from '@rsuite/icons/PageEnd'; const App = () => ( <ButtonToolbar> <Button endIcon={<FaExternalLinkSquareAlt />}> Open on new tab </Button> <Button endIcon={<PageEndIcon />}> Next page </Button> </ButtonToolbar> ); ReactDOM.render(<App />, document.getElementById('root'));

从源码看（Button.tsx），图标会被包裹在<span class="rs-btn-start-icon">/<span class="rs-btn-end-icon">中，图标与文字间距由--rs-btn-icon-gap（默认 5px）控制，图标大小则跟随前面提到的--rs-btn-icon-size变量自动适配size。

适应容器宽度：block 属性

block为boolean类型，使按钮拉伸为块级、占满父容器宽度（block.md）：

import { Button, ButtonToolbar } from 'rsuite'; import AddOutlineIcon from '@rsuite/icons/AddOutline'; const App = () => ( <ButtonToolbar> <Button appearance="default" block>Block</Button> <Button appearance="primary" block>Block Primary</Button> <Button block startIcon={<AddOutlineIcon />}>Block With Icon</Button> </ButtonToolbar> ); ReactDOM.render(<App />, document.getElementById('root'));

禁用、激活与加载状态

• 禁用（disabled）：所有外观均可禁用；注意即便按钮带有href，禁用后也不会响应跳转（disabled.md）：

import { Button, ButtonToolbar } from 'rsuite'; const App = () => ( <ButtonToolbar> <Button appearance="default" disabled>Default</Button> <Button appearance="primary" disabled>Primary</Button> <Button appearance="link" disabled href="https://rsuitejs.com">Link</Button> <Button appearance="subtle" disabled>Subtle</Button> <Button appearance="ghost" disabled>Ghost</Button> </ButtonToolbar> ); ReactDOM.render(<App />, document.getElementById('root'));

• 激活（active）：表示按钮处于当前选中态，静态声明active即可（active.md）：

<Button appearance="primary" active>Primary</Button>

• 加载中（loading）：按钮内会渲染加载指示器（loading.md）。从源码看（Button.tsx），loading为true时会渲染一个<span class="rs-btn-spin">，其直径由--rs-btn-loading-spin-default-diameter（18px，xs 尺寸为 16px）等变量控制，见 _variables.scss。

以上状态均以data-*属性形式写入 DOM：data-active、data-disabled、data-loading（Button.tsx），_mixin.scss 中的button-activated、button-pressed、button-disabled等 mixin 再基于这些属性选择器应用对应样式，使样式与状态一一对应、便于主题覆盖。

可切换按钮：toggleable 与 onToggle

toggleable（6.0.0 引入）让按钮可以在激活与非激活状态之间切换，点击时触发onToggle回调（toggleable.md）：

import { Button, ButtonGroup } from 'rsuite'; const App = () => ( <ButtonGroup> <Button toggleable>Bold</Button> <Button toggleable>Italic</Button> <Button toggleable>Underline</Button> </ButtonGroup> ); ReactDOM.render(<App />, document.getElementById('root'));

底层实现上，active状态由 useControlled 钩子管理，因此它既支持非受控用法（组件内部自行翻转状态），也支持受控用法（传入active后由外部接管状态）。点击逻辑见 handleClick：当toggleable为真时计算nextActive = !active，先更新内部状态，再回调onToggle?.(nextActive, event)，最后始终执行用户传入的onClick。需要留意的是，源码中onToggle的签名为(active: boolean, event: React.MouseEvent) => void（Button.tsx），即状态值在前、事件在后，编写回调时请以该顺序为准。

此外，toggleable按钮常配合 ButtonGroup 使用。从源码结构看，Button会读取ButtonGroupContext（Button.tsx），当自身未显式指定时，disabled与size会从父级ButtonGroup继承（第 73、77 行），这是“工具栏统一控制按钮尺寸/禁用”的实现来源。

Props 完整参考

<Button>

其中Appearance与Color类型定义见上文；onToggle的形参顺序以 Button.tsx 的类型声明为准。

源码级实现要点

• 渲染元素切换：as属性默认'button'；当传入href时自动切换为SafeAnchor（安全地渲染<a>元素）（Button.tsx）。若自定义as为其他元素类型，组件会自动补上role="button"以维持正确的 ARIA 语义（第 124 行）。
• 禁用属性的差异处理：对可原生禁用的元素（如<button>）使用disabled属性，否则降级为aria-disabled（Button.tsx）。
• type 默认值：未显式指定type且渲染为<button>时，默认注入type="button"，避免在表单中被误当作提交按钮（第 123 行）。
• 涟漪效果：ripple默认为true，但link与ghost外观不渲染 Ripple 元素（Button.tsx），与这两种外观“去边框/透明化”的轻量风格保持一致。
• 样式类前缀：classPrefix默认'btn'，配合useStyles生成rs-btn等类名；useCustom钩子则支持通过CustomProvider全局定制组件默认属性（Button.tsx）。
• 状态与测试：完整的 Props 定义与默认值在 Button.tsx 中可查证；行为与样式断言分别位于 Button.spec.tsx 和 Button.styles.spec.tsx。

可访问性

• ARIA 属性：Button 具有button的角色。当通过as自定义渲染元素时，源码会自动补上role="button"（Button.tsx）。
• 键盘交互：当 Button 获得焦点时，Space或Enter可以激活它。由于默认渲染为原生<button>，该行为由浏览器原生支持；with-focus-ringmixin（index.scss）同时保证了可见的焦点环。

相关参考

• 中文文档主入口：docs/pages/components/button/zh-CN/index.md
• 组件源码：src/Button/Button.tsx
• 组件导出：src/Button/index.tsx
• 样式实现：src/Button/styles/index.scss、src/Button/styles/_variables.scss、src/Button/styles/_mixin.scss
• 各场景演示片段：docs/pages/components/button/fragments
• 配套组件：ButtonGroup、ButtonToolbar、IconButton

• 前端
• UI组件