# 按钮

- 页面: https://jiguang132.com/zh/resources/ant-design/docs/button
- 资源: Ant Design (https://jiguang132.com/zh/resources/ant-design.md)
- 全部指南: https://jiguang132.com/zh/resources/ant-design/docs.md

按钮用于开始一个即时操作。


## 何时使用 {#when-to-use}

标记了一个（或封装一组）操作命令，响应用户点击行为，触发相应的业务逻辑。

在 Ant Design 中我们提供了五种按钮。

- 🔵 主按钮：用于主行动点，一个操作区域只能有一个主按钮。
- ⚪️ 默认按钮：用于没有主次之分的一组行动点。
- 😶 虚线按钮：常用于添加操作。
- 🔤 文本按钮：用于最次级的行动点。
- 🔗 链接按钮：一般用于链接，即导航至某位置。

以及四种状态属性与上面配合使用。

- ⚠️ 危险：删除/移动/修改权限等危险操作，一般需要二次确认。
- 👻 幽灵：用于背景色比较复杂的地方，常用在首页/产品页等展示场景。
- 🚫 禁用：行动点不可用的时候，一般需要文案解释。
- 🔃 加载中：用于异步操作等待反馈的时候，也可以避免多次提交。

## 代码演示 {#examples}


- 语法糖 · `basic`
- 颜色与变体 · `color-variant`

- 按钮图标 · `icon`
- 按钮图标位置 · `icon-placement`


- 按钮尺寸 · `size`
- 不可用状态 · `disabled`
- 加载中状态 · `loading`
- 多个按钮组合 · `multiple`
- 幽灵按钮 · `ghost`
- 危险按钮 · `danger`
- Block 按钮 · `block`



- 渐变按钮 · `linear-gradient`
- 自定义按钮波纹 · `wave`
- 移除两个汉字之间的空格 · `chinese-space`
- 自定义禁用样式背景 · `custom-disabled-bg`
- 自定义语义结构的样式和类 · `style-class`

## API

通用属性参考：[通用属性](#jguang-common-props)

通过设置 Button 的属性来产生不同的按钮样式，推荐顺序为：`type` -> `shape` -> `size` -> `loading` -> `disabled`。

按钮的属性说明如下：

| 属性 | 说明 | 类型 | 默认值 | 版本 | [全局配置](/components/config-provider#component-config) |
| --- | --- | --- | --- | --- | --- |
| autoInsertSpace | 我们默认提供两个汉字之间的空格，可以设置 `autoInsertSpace` 为 `false` 关闭 | boolean | `true` | 5.17.0 | 5.17.0 |
| block | 将按钮宽度调整为其父宽度的选项 | boolean | false |  | × |
| classNames | 用于自定义组件内部各语义化结构的 class，支持对象或函数 | Record<[SemanticDOM](#semantic-dom), string> \| (info: { props })=> Record<[SemanticDOM](#semantic-dom), string> | - | 6.0.0 | 6.0.0 |
| color | 设置按钮的颜色 | `default` \| `primary` \| `danger` \| [PresetColors](#presetcolors) | `variant="solid"` 时为 `primary` | `default`、`primary` 和 `danger`: 5.21.0, `PresetColors`: 5.23.0, `solid` 默认颜色: 6.4.0 | 5.25.0 |
| danger | 语法糖，设置危险按钮。当设置 `color` 时会以后者为准 | boolean | false |  | × |
| disabled | 设置按钮失效状态 | boolean | false |  | × |
| ghost | 幽灵属性，使按钮背景透明 | boolean | false |  | × |
| href | 点击跳转的地址，指定此属性 button 的行为和 a 链接一致 | string | - |  | × |
| htmlType | 设置 `button` 原生的 `type` 值，可选值请参考 [HTML 标准](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Element/button#type) | `submit` \| `reset` \| `button` | `button` |  | × |
| icon | 设置按钮的图标组件 | ReactNode | - |  | × |
| iconPlacement | 设置按钮图标组件的位置 | `start` \| `end` | `start` | - | × |
| ~~iconPosition~~ | 设置按钮图标组件的位置,请使用 `iconPlacement` 替换 | `start` \| `end` | `start` | 5.17.0 | × |
| loading | 设置按钮载入状态 | boolean \| { delay: number, icon: ReactNode } | false | icon: 5.23.0 | × |
| loadingIcon | （仅支持全局配置）设置按钮的加载图标 | ReactNode | `<LoadingOutlined />` |  | 6.3.0 |
| onClick | 点击按钮时的回调 | (event: React.MouseEvent<HTMLElement, MouseEvent>) => void | - |  | × |
| shape | 设置按钮形状 | `default` \| `circle` \| `round` | `default` |  | 5.27.0 |
| size | 设置按钮大小 | `large` \| `medium` \| `small` | `medium` |  | × |
| styles | 用于自定义组件内部各语义化结构的行内 style，支持对象或函数 | Record<[SemanticDOM](#semantic-dom), CSSProperties> \| (info: { props })=> Record<[SemanticDOM](#semantic-dom), CSSProperties> | - | 6.0.0 | 6.0.0 |
| target | 相当于 a 链接的 target 属性，href 存在时生效 | string | - |  | × |
| type | 语法糖，设置按钮类型。当设置 `variant` 与 `color` 时以后者为准 | `primary` \| `dashed` \| `link` \| `text` \| `default` | `default` |  | × |
| variant | 设置按钮的变体 | `outlined` \| `dashed` \| `solid` \| `filled` \| `text` \| `link` | - | 5.21.0 | 5.25.0 |

支持原生 button 的其他所有属性。

### PresetColors

> type PresetColors = 'blue' | 'purple' | 'cyan' | 'green' | 'magenta' | 'pink' | 'red' | 'orange' | 'yellow' | 'volcano' | 'geekblue' | 'lime' | 'gold';

## Semantic DOM


| 语义节点 | 原生说明 | 版本 |
| --- | --- | --- |
| `root` | 根元素，包含边框样式、背景色、内边距、圆角、阴影效果、过渡动画、光标样式、文字权重、对齐方式等完整的按钮外观样式 | 6.0.0 |
| `icon` | 图标元素，包含图标的字体大小、颜色继承、SVG 样式重置等图标显示相关样式 | 5.5.0 |
| `content` | 内容元素，包装按钮文本内容，控制文本的不换行显示、居中对齐、中文字符间距优化等文本排版样式 | 6.0.0 |

语义说明来源: `vendor/components/button/demo/_semantic.tsx`

## 主题变量（Design Token）{#design-token}

类型、继承关系和原生令牌声明保持固定源码原文；默认值由原生主题计算，并可能受 ConfigProvider 覆盖。本表不伪造静态默认值。

| 令牌 | 类型 | 原生说明 |
| --- | --- | --- |
| `fontWeight` | `CSSProperties['fontWeight']` | 文字字重 |
| `iconGap` | `CSSProperties['gap']` | 图标文字间距 |
| `defaultShadow` | `string` | 默认按钮阴影 |
| `primaryShadow` | `string` | 主要按钮阴影 |
| `dangerShadow` | `string` | 危险按钮阴影 |
| `primaryColor` | `string` | 主要按钮文本颜色 |
| `defaultColor` | `string` | 默认按钮文本颜色 |
| `defaultBg` | `string` | 默认按钮背景色 |
| `defaultBorderColor` | `string` | 默认按钮边框颜色 |
| `dangerColor` | `string` | 危险按钮文本颜色 |
| `defaultHoverBg` | `string` | 默认按钮悬浮态背景色 |
| `defaultHoverColor` | `string` | 默认按钮悬浮态文本颜色 |
| `defaultHoverBorderColor` | `string` | 默认按钮悬浮态边框颜色 |
| `defaultActiveBg` | `string` | 默认按钮激活态背景色 |
| `defaultActiveColor` | `string` | 默认按钮激活态文字颜色 |
| `defaultActiveBorderColor` | `string` | 默认按钮激活态边框颜色 |
| `borderColorDisabled` | `string` | 禁用状态边框颜色 |
| `defaultGhostColor` | `string` | 默认幽灵按钮文本颜色 |
| `ghostBg` | `string` | 幽灵按钮背景色 |
| `defaultGhostBorderColor` | `string` | 默认幽灵按钮边框颜色 |
| `solidTextColor` | `string` | 默认实心按钮的文本色 |
| `textTextColor` | `string` | 默认文本按钮的文本色 |
| `textTextHoverColor` | `string` | 默认文本按钮悬浮态文本颜色 |
| `textTextActiveColor` | `string` | 默认文本按钮激活态文字颜色 |
| `paddingInline` | `CSSProperties['paddingInline']` | 按钮横向内间距 |
| `paddingInlineLG` | `CSSProperties['paddingInline']` | 大号按钮横向内间距 |
| `paddingInlineSM` | `CSSProperties['paddingInline']` | 小号按钮横向内间距 |
| `paddingBlock` | `CSSProperties['paddingBlock']` | 按钮纵向内间距 |
| `paddingBlockLG` | `CSSProperties['paddingBlock']` | 大号按钮纵向内间距 |
| `paddingBlockSM` | `CSSProperties['paddingBlock']` | 小号按钮纵向内间距 |
| `onlyIconSize` | `number \| string` | 只有图标的按钮图标尺寸 |
| `onlyIconSizeLG` | `number \| string` | 大号只有图标的按钮图标尺寸 |
| `onlyIconSizeSM` | `number \| string` | 小号只有图标的按钮图标尺寸 |
| `linkHoverBg` | `string` | 链接按钮悬浮态背景色 |
| `textHoverBg` | `string` | 文本按钮悬浮态背景色 |
| `contentFontSize` | `number` | 按钮内容字体大小 |
| `contentFontSizeLG` | `number` | 大号按钮内容字体大小 |
| `contentFontSizeSM` | `number` | 小号按钮内容字体大小 |
| `contentLineHeight` | `number` | 按钮内容字体行高 |
| `contentLineHeightLG` | `number` | 大号按钮内容字体行高 |
| `contentLineHeightSM` | `number` | 小号按钮内容字体行高 |
| `defaultBgDisabled` | `string` | type='default' 禁用状态下的背景颜色 |
| `dashedBgDisabled` | `string` | type='dashed' 禁用状态下的背景颜色 |

声明来源: `vendor/components/button/style/token.ts`

```ts
import type { CSSProperties } from 'react';

import type { CSSObject } from '@ant-design/cssinjs';

import { unit } from '@ant-design/cssinjs';

import { AggregationColor } from '../../color-picker/color';

import { isBright } from '../../color-picker/components/ColorPresets';

import { PresetColors } from '../../theme/interface';

import type { FullToken, GenStyleFn, GetDefaultToken, PresetColorKey } from '../../theme/internal';

import { getLineHeight, mergeToken } from '../../theme/internal';

import getAlphaColor from '../../theme/util/getAlphaColor';

/** Component only token. Which will handle additional calculation of alias token */
export interface ComponentToken {
  /**
   * @desc 文字字重
   * @descEN Font weight of text
   */
  fontWeight: CSSProperties['fontWeight'];
  /**
   * @desc 图标文字间距
   * @descEN Gap between icon and text
   */
  iconGap: CSSProperties['gap'];
  /**
   * @desc 默认按钮阴影
   * @descEN Shadow of default button
   */
  defaultShadow: string;
  /**
   * @desc 主要按钮阴影
   * @descEN Shadow of primary button
   */
  primaryShadow: string;
  /**
   * @desc 危险按钮阴影
   * @descEN Shadow of danger button
   */
  dangerShadow: string;
  /**
   * @desc 主要按钮文本颜色
   * @descEN Text color of primary button
   */
  primaryColor: string;
  /**
   * @desc 默认按钮文本颜色
   * @descEN Text color of default button
   */
  defaultColor: string;
  /**
   * @desc 默认按钮背景色
   * @descEN Background color of default button
   */
  defaultBg: string;
  /**
   * @desc 默认按钮边框颜色
   * @descEN Border color of default button
   */
  defaultBorderColor: string;
  /**
   * @desc 危险按钮文本颜色
   * @descEN Text color of danger button
   */
  dangerColor: string;
  /**
   * @desc 默认按钮悬浮态背景色
   * @descEN Background color of default button when hover
   */
  defaultHoverBg: string;
  /**
   * @desc 默认按钮悬浮态文本颜色
   * @descEN Text color of default button when hover
   */
  defaultHoverColor: string;
  /**
   * @desc 默认按钮悬浮态边框颜色
   * @descEN Border color of default button
   */
  defaultHoverBorderColor: string;
  /**
   * @desc 默认按钮激活态背景色
   * @descEN Background color of default button when active
   */
  defaultActiveBg: string;
  /**
   * @desc 默认按钮激活态文字颜色
   * @descEN Text color of default button when active
   */
  defaultActiveColor: string;
  /**
   * @desc 默认按钮激活态边框颜色
   * @descEN Border color of default button when active
   */
  defaultActiveBorderColor: string;
  /**
   * @deprecated use `colorBorderDisabled` instead
   * @desc 禁用状态边框颜色
   * @descEN Border color of disabled button
   */
  borderColorDisabled: string;
  /**
   * @desc 默认幽灵按钮文本颜色
   * @descEN Text color of default ghost button
   */
  defaultGhostColor: string;
  /**
   * @desc 幽灵按钮背景色
   * @descEN Background color of ghost button
   */
  ghostBg: string;
  /**
   * @desc 默认幽灵按钮边框颜色
   * @descEN Border color of default ghost button
   */
  defaultGhostBorderColor: string;
  /**
   * @desc 主要填充按钮的浅色背景颜色
   * @descEN Background color of primary filled button
   */
  /**
   * @desc 默认实心按钮的文本色
   * @descEN Default text color for solid buttons.
   */
  solidTextColor: string;
  /**
   * @desc 默认文本按钮的文本色
   * @descEN Default text color for text buttons
   */
  textTextColor: string;
  /**
   * @desc 默认文本按钮悬浮态文本颜色
   * @descEN Default text color for text buttons on hover
   */
  textTextHoverColor: string;
  /**
   * @desc 默认文本按钮激活态文字颜色
   * @descEN Default text color for text buttons on active
   */
  textTextActiveColor: string;
  /**
   * @desc 按钮横向内间距
   * @descEN Horizontal padding of button
   */
  paddingInline: CSSProperties['paddingInline'];
  /**
   * @desc 大号按钮横向内间距
   * @descEN Horizontal padding of large button
   */
  paddingInlineLG: CSSProperties['paddingInline'];
  /**
   * @desc 小号按钮横向内间距
   * @descEN Horizontal padding of small button
   */
  paddingInlineSM: CSSProperties['paddingInline'];
  /**
   * @desc 按钮纵向内间距
   * @descEN Vertical padding of button
   * @deprecated not used
   */
  paddingBlock: CSSProperties['paddingBlock'];
  /**
   * @desc 大号按钮纵向内间距
   * @descEN Vertical padding of large button
   * @deprecated not used
   */
  paddingBlockLG: CSSProperties['paddingBlock'];
  /**
   * @desc 小号按钮纵向内间距
   * @descEN Vertical padding of small button
   * @deprecated not used
   */
  paddingBlockSM: CSSProperties['paddingBlock'];
  /**
   * @desc 只有图标的按钮图标尺寸
   * @descEN Icon size of button which only contains icon
   */
  onlyIconSize: number | string;
  /**
   * @desc 大号只有图标的按钮图标尺寸
   * @descEN Icon size of large button which only contains icon
   */
  onlyIconSizeLG: number | string;
  /**
   * @desc 小号只有图标的按钮图标尺寸
   * @descEN Icon size of small button which only contains icon
   */
  onlyIconSizeSM: number | string;
  /**
   * @desc 链接按钮悬浮态背景色
   * @descEN Background color of link button when hover
   */
  linkHoverBg: string;
  /**
   * @desc 文本按钮悬浮态背景色
   * @descEN Background color of text button when hover
   */
  textHoverBg: string;
  /**
   * @desc 按钮内容字体大小
   * @descEN Font size of button content
   */
  contentFontSize: number;
  /**
   * @desc 大号按钮内容字体大小
   * @descEN Font size of large button content
   */
  contentFontSizeLG: number;
  /**
   * @desc 小号按钮内容字体大小
   * @descEN Font size of small button content
   */
  contentFontSizeSM: number;
  /**
   * @desc 按钮内容字体行高
   * @descEN Line height of button content
   * @deprecated not used
   */
  contentLineHeight: number;
  /**
   * @desc 大号按钮内容字体行高
   * @descEN Line height of large button content
   * @deprecated not used
   */
  contentLineHeightLG: number;
  /**
   * @desc 小号按钮内容字体行高
   * @descEN Line height of small button content
   * @deprecated not used
   */
  contentLineHeightSM: number;
  /**
   * @desc type='default' 禁用状态下的背景颜色
   * @descE background color when type='default' is disabled
   */
  defaultBgDisabled: string;
  /**
   * @desc type='dashed' 禁用状态下的背景颜色
   * @descE background color when type='dashed' is disabled
   */
  dashedBgDisabled: string;
}

type ShadowColorMap = {
  /**
   * @desc 预设按钮的阴影色
   * @descEN Shadow colors of preset button
   */
  [Key in `${PresetColorKey}ShadowColor`]: string;
};

type PresetColorHoverActiveMap = {
  [Key in `${PresetColorKey}Hover` | `${PresetColorKey}Active`]: string;
};

type GroupToken = {
  /**
   * @desc 按钮组边框颜色
   * @descEN Border color of button group
   * @internal Button.Group 已废弃相关token不应该在显示在文档上
   */

  groupBorderColor: string;
};

export interface ButtonToken
  extends FullToken<'Button'>,
    ShadowColorMap,
    PresetColorHoverActiveMap,
    GroupToken {
  /**
   * @desc 按钮横向内边距
   * @descEN Horizontal padding of button
   */
  buttonPaddingHorizontal: CSSProperties['paddingInline'];
  /**
   * @desc 按钮纵向内边距
   * @descEN Vertical padding of button
   */
  buttonPaddingVertical: CSSProperties['paddingBlock'];
  /**
   * @desc 只有图标的按钮图标尺寸
   * @descEN Icon size of button which only contains icon
   */
  buttonIconOnlyFontSize: number | string;
}
```

## FAQ

### 类型和颜色与变体如何选择？ {#faq-type-color-variant}

类型本质上是颜色与变体的语法糖，内部为其提供了一组颜色与变体的映射关系。如果两者同时存在，优先使用颜色与变体。

```jsx
<Button type="primary">click</Button>
```

等同于

```jsx
<Button color="primary" variant="solid">
  click
</Button>
```

### 如何关闭点击波纹效果？ {#faq-close-wave-effect}

如果你不需要这个特性，可以设置 [ConfigProvider](/components/config-provider#api) 的 `wave` 的 `disabled` 为 `true`。

```jsx
<ConfigProvider wave={{ disabled: true }}>
  <Button>click</Button>
</ConfigProvider>
```



## 设计指引 {#design-guide}

- [我的按钮究竟该放哪儿！？| Ant Design 4.0 系列分享](https://zhuanlan.zhihu.com/p/109644406)


## 原生通用属性 {#jguang-common-props}


> Tips: 以下通用属性适用于 antd 大部分组件，不支持的组件会单独说明。

| 参数 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| style | 自定义样式 | CSSProperties | - |
| className | 自定义类名 | string | - |
| rootClassName | 添加在组件最外层的 className | string | - |
| autoFocus | 自动获取焦点，仅对表单类、链接、交互容器等可聚焦元素生效 | boolean | false |


## 安装并复现示例

```bash
npm install antd@6.6.5 @ant-design/icons@6.3.4 dayjs@1.11.23
```

使用 ConfigProvider 和原生 App，并单独配置 dayjs 语言。每个示例在查看代码中列出完整源码文件和额外固定依赖。示例名称用于选择演示，不是组件通用属性。主题、语言与 SSR 初始化见资源安装指南。

## 原生类型参考

源码查看器包含未修改的原生实现和以下声明文件，继承类型仍位于原生包中。代码中的英文注释保留为源码参考。

- `vendor/components/button/Button.tsx`
- `vendor/components/button/ButtonGroup.tsx`
- `vendor/components/button/DefaultLoadingIcon.tsx`
- `vendor/components/button/IconWrapper.tsx`
- `vendor/components/button/buttonHelpers.tsx`
- `vendor/components/button/style/token.ts`

## 来源与许可

https://github.com/ant-design/ant-design/tree/4a39f54842eade4e565ab336ef6097cd7e723cdd

保留原生中英文正文与可执行示例；官网专用的嵌入章节和令牌表格在本地展开。Ant Design 使用 MIT 许可，另列依赖的许可证也需保留。上传预览禁止向外发起请求，不提供后端服务。

---

JGuang 全部资源索引: https://jiguang132.com/llms.txt