u

code/g3soft-libs/docs/content/ui/2.general/button-group.md

@@ -0,0 +1,64 @@
+---
+title: ButtonGroup 按钮组
+description: 把多个按钮贴合排列成一组，适用于工具条与互斥动作
+---
+
+# ButtonGroup 按钮组
+
+按钮组把多个 `G3Button` 贴合排列：组内按钮去掉相邻圆角、边框重叠 1px，视觉上成为一整块。它只负责**布局**，每个按钮的 `type` / `size` / `disabled` 仍由自己决定。
+
+## 何时使用
+
+- 多个同层级操作成排出现（工具栏、卡片操作区）时，用按钮组把它们的关联关系表达出来；
+- 一组图标动作（左对齐 / 居中 / 右对齐）时使用，避免按钮之间出现缝隙；
+- 只是想给按钮之间加间距，请用 [Space 间距](/ui/general/space)，不要用按钮组。
+
+## 基础用法
+
+默认水平排列，组内按钮共用一套圆角与边框。
+
+:::demo{name="button-group/basic"}
+:::
+
+## 纵向排列
+
+`orientation="vertical"` 时纵向贴合，组内按钮宽度一致，常作为侧边操作组。
+
+:::demo{name="button-group/vertical"}
+:::
+
+## 组合不同变体与尺寸
+
+组内按钮各自保留 `type` / `size`；混排时建议统一变体，否则视觉层次会混乱。
+
+:::demo{name="button-group/variant"}
+:::
+
+## 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` 浮到上层，避免焦点环被相邻按钮挡住。