# Button 按钮 · HeroUI

> 可点击的按钮组件，支持多种变体与状态。

- 页面: https://jiguang132.com/zh/systems/heroui/docs/components/button
- 改编自: HeroUI 文档 (Apache-2.0) @ 60edd8ed751b1d2a270623fbb182bbcfa8baa9af

## 引入

```tsx
import { Button } from '@heroui/react';
```

### 用法


> 示例 `button-basic`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/components/button


### 变体


> 示例 `button-variants`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/components/button


### 带图标


> 示例 `button-with-icons`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/components/button


### 仅图标


> 示例 `button-icon-only`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/components/button


### 加载中


> 示例 `button-loading`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/components/button


### 加载状态


> 示例 `button-loading-state`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/components/button


### 尺寸


> 示例 `button-sizes`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/components/button


### 全宽


> 示例 `button-full-width`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/components/button


### 禁用状态


> 示例 `button-disabled`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/components/button


### 社交按钮


> 示例 `button-social`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/components/button


### 自定义渲染函数


> 示例 `button-custom-render-function`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/components/button


## 样式

### 传入 Tailwind CSS 类

```tsx
import { Button } from '@heroui/react';

function CustomButton() {
  return (
    <Button className="bg-purple-500 text-white hover:bg-purple-600">
      Purple Button
    </Button>
  );
}
```

### 自定义组件类

若要自定义 Button 组件类，可以使用 `@layer components` 指令。
  
[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。

```css
@layer components {
  .button {
    @apply bg-purple-500 text-white hover:bg-purple-600;
  }

  .button--icon-only {
    @apply rounded-lg bg-blue-500;
  }
}
```

HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。

### 添加自定义变体

你可以通过封装 HeroUI 组件并添加自定义变体来扩展其能力。


> 示例 `button-custom-variants`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/components/button


### 添加涟漪效果

Button 组件支持通过组合方式实现涟漪效果，你可以将涟漪组件作为子节点嵌套。此示例使用 [m3-ripple](https://github.com/saltyaom/m3-ripple)。


> 示例 `button-ripple-effect`: 交互预览见 https://jiguang132.com/zh/systems/heroui/docs/components/button


### CSS 类

Button 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/button.css)）：

#### 基础与尺寸类
- `.button` - 按钮基础样式
- `.button--sm` - 小尺寸变体
- `.button--md` - 中尺寸变体
- `.button--lg` - 大尺寸变体

#### 变体类
- `.button--primary`
- `.button--secondary`
- `.button--tertiary`
- `.button--outline`
- `.button--ghost`
- `.button--danger`

#### 修饰符类
- `.button--icon-only`
- `.button--icon-only.button--sm`
- `.button--icon-only.button--lg`

### 交互状态

该按钮同时支持 CSS 伪类与 data 属性，以提供更灵活的状态控制：

- **悬停**：`:hover` 或 `[data-hovered="true"]`
- **激活/按压**：`:active` 或 `[data-pressed="true"]`（包含缩放变换）
- **聚焦**：`:focus-visible` 或 `[data-focus-visible="true"]`（显示焦点环）
- **禁用**：`:disabled` 或 `[aria-disabled="true"]`（降低透明度，禁用指针事件）
- **等待中**：`[data-pending]`（加载期间禁用指针事件）

## API 参考

### Button Props

| Prop | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| `variant` | `'primary' \| 'secondary' \| 'tertiary' \| 'outline' \| 'ghost' \| 'danger'` | `'primary'` | 视觉样式变体 |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | 按钮尺寸 |
| `fullWidth` | `boolean` | `false` | 按钮是否占满容器宽度 |
| `isDisabled` | `boolean` | `false` | 按钮是否禁用 |
| `isPending` | `boolean` | `false` | 按钮是否处于加载状态 |
| `isIconOnly` | `boolean` | `false` | 按钮是否仅包含图标 |
| `onPress` | `(e: PressEvent) => void` | - | 按钮被按下时的事件处理函数 |
| `children` | `React.ReactNode \| (values: ButtonRenderProps) => React.ReactNode` | - | 按钮内容或渲染 prop |
| `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, ButtonRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。|

### ButtonRenderProps

使用渲染 prop 模式时，会提供以下值：

| Prop | 类型 | 描述 |
|------|------|------|
| `isPending` | `boolean` | 按钮是否处于加载状态 |
| `isPressed` | `boolean` | 按钮当前是否被按压 |
| `isHovered` | `boolean` | 按钮是否处于悬停状态 |
| `isFocused` | `boolean` | 按钮是否处于聚焦状态 |
| `isFocusVisible` | `boolean` | 按钮是否应显示焦点指示 |
| `isDisabled` | `boolean` | 按钮是否禁用 |

---

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