---
title: ButtonGroup 按钮组
description: 把多个按钮贴合排列成一组，适用于工具条与互斥动作
---

# ButtonGroup 按钮组

按钮组把多个 `G3Button` 贴合排列：组内按钮去掉相邻圆角、边框重叠 1px，视觉上成为一整块。它只负责**布局**，每个按钮的 `type` / `size` / `disabled` 仍由自己决定。

## 何时使用

- 多个同层级操作成排出现（工具栏、卡片操作区）时，用按钮组把它们的关联关系表达出来；
- 一组图标动作（左对齐 / 居中 / 右对齐）时使用，避免按钮之间出现缝隙；
- 只是想给按钮之间加间距，请用 [Space 间距](/ui/general/space)，不要用按钮组。

## 基础用法

默认水平排列，组内按钮共用一套圆角与边框。

<demo vue="button-group/basic.vue" />

## 纵向排列

`orientation="vertical"` 时纵向贴合，组内按钮宽度一致，常作为侧边操作组。

<demo vue="button-group/vertical.vue" />

## 组合不同变体与尺寸

组内按钮各自保留 `type` / `size`；混排时建议统一变体，否则视觉层次会混乱。

<demo vue="button-group/variant.vue" />

## API

### Props（ButtonGroup）

| 名称 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | 排列方向。`vertical` 时纵向贴合、按钮等宽 |

### Slots

| 名称 | 参数 | 说明 |
| --- | --- | --- |
| `default` | — | 组内的 `G3Button`。非按钮元素不会被索引到圆角规则里，请勿放置 |

### 类型定义

```ts
export interface ButtonGroupProps {
  orientation?: 'horizontal' | 'vertical'
}
```

## 实现说明

- 组内按钮通过 `margin-left: -1px` 让相邻边框重叠，避免出现 2px 的双线；
- 首尾按钮单独恢复圆角，因此**中间的按钮不要插非按钮元素**（会被 CSS 的 `:first-child` / `:last-child` 规则错位）；
- 分组用 `role="group"` 标注，屏幕阅读器会把它们视为一组操作；
- 按钮聚焦时会 `z-index: 1` 浮到上层，避免焦点环被相邻按钮挡住。