ButtonGroup 按钮组
将一组相关操作组合为连续的按钮控件。
用法
组合相关操作
组件结构
加粗的是必需部件。
data-scope="button-group"：root
示例
变体
设置整组外观
主要
次要
第三
线框
幽灵
危险
尺寸
设置整组尺寸
方向
水平或垂直排列
图标与标签
组合图标按钮与文字按钮
宽度充满
按钮等分可用宽度
禁用
禁用整组按钮
无分隔线
省略分隔线部件
设计指引
何时使用
- 并列展示作用相近的操作。
- 统一一组按钮的尺寸、变体和颜色。
何时不用
- 需要表达单选或多选状态时，使用切换按钮组。
- 操作之间没有直接关系时，分别放置按钮并保留间距。
特性
- 支持水平和垂直排列。
- 自动合并相邻边界，只保留首尾圆角。
- 支持统一设置尺寸、变体、颜色、禁用状态和宽度：组的变体、颜色与尺寸下发到组内每一段，段自己写了的优先。
- 组的缺省变体是中性淡底
subtle，不是单独一枚按钮的品牌实心。 - 默认在相邻按钮之间显示分隔线，可通过
separators=false关闭。 - 按下按钮时不缩放，避免组内边界断开。
组合
- 在组内直接放置按钮。
- 将菜单触发器放在末尾，可组成分裂按钮。
最佳实践
- 每组只放置同一任务下的操作。
- 操作较多时，保留常用项，其余收纳到菜单中。
- 窄容器中使用垂直方向，不要让按钮组换行。
- 尺寸和变体优先设置在按钮组上。
反模式
- 不要用按钮组表示已选中项。
- 不要在按钮之间插入说明文字。
API 参考
产物
| 层 | 值 |
|---|---|
| 自定义元素 | <xh-button-group> |
| Vue 组件 | XhButtonGroup |
| 状态机 | 无，connect 直接由 props 算属性 |
| 皮肤 | @xihan-ui/styles/button-group.css |
Props
| 属性 | 类型 | 必填 | 说明 |
|---|---|---|---|
disabled | boolean | 整组禁用：适配器把它落到组内每一段的原生 disabled 上，段自身声明禁用的仍然禁用。 | |
fullWidth | boolean | 撑满行宽：整组占满可用宽度，每段等分剩余空间。 | |
orientation | 'horizontal' | 'vertical' | 排布：horizontal / vertical，决定相邻两段在哪个轴上合并边缘。 | |
separators | boolean | 是否自动在相邻按钮之间插入分隔线，默认 true。 | |
size | Size | 尺寸：sm / md / lg，写入根上并下发给组内每一段；段自己写了的优先。 | |
tone | Tone | 颜色：brand / neutral / success / warning / danger / info，写入根上并下发给组内每一段；段自己写了的优先。 | |
variant | ActionVariant | 变体：solid / subtle / outline / ghost，默认 subtle（组缺省中性淡底）。 写入根上，并由适配器下发给组内每一段；段自己写了 variant 的优先。 |
connect API
getXxxProps() 返回对应部件的宿主属性。
| 成员 | 类型 | 说明 |
|---|---|---|
orientation | 'horizontal' | 'vertical' | |
disabled | boolean | 整组是否禁用。适配器据此把禁用传给组内每一段：只写 data-* 是假禁用。 |
separators | boolean | 适配器是否自动生成相邻按钮间的分隔线。 |
variant | ActionVariant | 组的变体（缺省 subtle）。适配器把它下发给未自写 variant 的每一段，段因此自带形态矩阵属性。 |
tone | Tone | undefined | 组的颜色；未写时为 undefined，段沿用自己的。适配器下发给未自写 tone 的每一段。 |
size | Size | undefined | 组的尺寸；未写时为 undefined，段沿用自己的。适配器下发给未自写 size 的每一段。 |
getRootProps | () => T['element'] |
无障碍
键盘
规格出处：W3C APG
无键盘交互（不接收焦点，或焦点行为完全由原生元素提供）。
ARIA
以下属性由 connect 生成。
| 部件 | 属性 | 值 |
|---|---|---|
root | role | 'group' |
样式参考
皮肤
@xihan-ui/styles/button-group.css 使用 [data-scope="button-group"][data-part="root"] 部件选择器，位于 xihan.components 层。覆盖样式使用 xihan.overrides。
forced-colors: active 下另有一套规则：颜色交给系统，边框与状态标记改用系统色关键字。
数据属性
由 connect 生成；条件不成立时不输出无值属性。
| 部件 | 属性 | 值 |
|---|---|---|
root | data-disabled | ''（条件成立时才出现） |
root | data-full-width | ''（条件成立时才出现） |
root | data-orientation | props.orientation |
root | data-size | props.size |
root | data-tone | props.tone |
root | data-variant | props.variant |
CSS 变量
本组件公开覆盖槽由独立皮肤的实际消费位生成；默认来源、作用部件和状态均与 CSS 同源。
| 变量 | 部件 | CSS 属性 | 状态 | 默认来源 | 说明 |
|---|---|---|---|---|---|
--xh-button-group-outline-color | root | border | variant=outline | --xh-_tone-border-control | button-group 的 root 部件 border 覆盖槽。 |
--xh-button-group-radius | root | border-end-end-radiusborder-end-start-radiusborder-radiusborder-start-end-radiusborder-start-start-radius | first-childlast-childorientation=horizontalorientation=verticalvariant=outline | --xh-shape-control | button-group 的 root 部件 border-end-end-radius、border-end-start-radius、border-radius、border-start-end-radius、border-start-start-radius 覆盖槽。 |
--xh-button-group-separator-color | root | background | xh-button-group-separator | --xh-fg-default | button-group 的 root 部件 background 覆盖槽。 |
--xh-button-group-separator-color-disabled | root | background | disabledxh-button-group-separator | --xh-border-subtle | button-group 的 root 部件 background 覆盖槽。 |
--xh-button-group-separator-opacity | root | opacity | xh-button-group-separator | --xh-control-separator-opacity | button-group 的 root 部件 opacity 覆盖槽。 |
--xh-button-group-separator-opacity-disabled | root | opacity | disabledxh-button-group-separator | --xh-control-separator-disabled-opacity | button-group 的 root 部件 opacity 覆盖槽。 |
--xh-button-group-separator-radius | root | border-radius | xh-button-group-separator | --xh-shape-pill | button-group 的 root 部件 border-radius 覆盖槽。 |
--xh-button-group-separator-size | root | block-sizeinline-size | orientation=horizontalorientation=verticalxh-button-group-separator | --xh-_group-separator-size | button-group 的 root 部件 block-size、inline-size 覆盖槽。 |
--xh-button-group-separator-thickness | root | block-sizeinline-sizemargin-block-startmargin-inline-start | orientation=horizontalorientation=verticalxh-button-group-separator | --xh-stroke-thin | button-group 的 root 部件 block-size、inline-size、margin-block-start、margin-inline-start 覆盖槽。 |
动效
动效角色：状态（见动效规范）。
background-color · opacity 走 transition 过渡。时长与缓动读动效令牌，改令牌即改全局节奏。
系统开启减弱动效时由令牌层统一收敛，皮肤不另作判断。
RTL
皮肤用逻辑属性排布（inline-start 一族），dir="rtl" 下自动镜像。