ButtonGroup 使用手册

许可阅读：首次阅读组件文档、源码或 npm 使用流程，先读完整 LICENSE；同任务同版本去重。公开 API 配置与内部实现修改分别按许可处理；全部组件使用统一运行包，源码权益以许可为准。

组件介绍

将相关按钮组合为统一的操作组，支持分割线，适合拆分按钮和紧凑工具栏。

使用选择

用于排列相关按钮并统一组内组合。需要不足宽度时收进更多菜单，用 OverflowActions。

• 直接放置 Button 即可形成分组；内置分割线由 showSeparator 控制。

• 组统一提供 variant / size / disabled 等配置；子 Button 的显式 size 可覆盖组尺寸。

快速开始

以下示例展示推荐的基本组合。更多场景与组合限制见后文。

<script lang="ts">	import { Button, ButtonGroup } from '@snowui-design-system/components';	import { BookOpen, FigmaLogo, GithubLogo } from '@snowui-design-system/resource-svelte';</script> <ButtonGroup aria-label="Button component resources">	<Button as="item"><BookOpen />Docs</Button>	<Button as="item"><GithubLogo />Source</Button>	<Button as="item"><FigmaLogo />Figma</Button></ButtonGroup>

API

未重新声明的继承能力请查所属基础组件文档；本表只列本组件源码具名公开属性。

使用边界与详细说明

组件边界

• ButtonGroup 属于 组件，作用半径只覆盖自身一个 Frame 容器，不依赖专业协调模块 的跨 Frame 编排能力。

• variant 对齐 Button 的 gray / filled / outline / borderless。初版不开放 link，因为 link 形态没有稳定按钮外壳，不适合承载分割线。

• ButtonGroup 不内置 Popover / Menu 行为。需要菜单时，消费方把 Popover 触发器或菜单图标放入某个 Button 单元格。

• ButtonGroup 不提供专用 Cell 组件。单元格直接复用 Button，避免平行维护第二套按钮事件、链接、状态、图标尺寸与无障碍逻辑。

• ButtonGroup 不改变 Button 的 bare 无外壳语义；单 Icon 的尺寸上下文与透明点击热区继续由 Button 自动处理。

• ButtonGroup 中多个 Button 共同构成一个复合控件，item 默认 scaleOnHover=false，避免相邻单元格互相覆盖；子 Button 可显式传 scaleOnHover={true} 重新开启。

结构规则

单元格直接使用 Button，相邻 item 之间默认由 ButtonGroup 绘制装饰性分割线：

<ButtonGroup>  <Button as="item" onclick={copy}>    <Icon><Copy /></Icon>    <Text>Copy</Text>  </Button>  <Button as="item" onclick={openMore}>    <Icon><ChevronDown /></Icon>    <Text>More</Text>  </Button></ButtonGroup>

不需要分割线时关闭内置显示：

<ButtonGroup showSeparator={false}>  <Button as="item">Previous</Button>  <Button as="item">Next</Button></ButtonGroup>

旧代码中的直系 Separator as="separator" 会被 ButtonGroup 隐藏，避免升级后与内置分割线重复；应在迁移时删除这些手工 Separator。其他显式内容仍按普通容器内容渲染，不会被当作 ButtonGroup item。

内部 Button 作为 ButtonGroup 的直系子项时自动进入嵌入态：

• 保留独立 onclick / href / 状态机 / 动效 / 无障碍能力。

• 退掉自身背景、边框和圆角，但接收 ButtonGroup 分配的单元格 padding。

• 保留自身内容布局与单元格内 gap。

• 默认继承 ButtonGroup 的 size / variant / disabled，实例显式传值可覆盖 size / variant。

• ButtonGroup 会自动标记直系 Button 的单元格位置：only / first / middle / last，消费方不需要手写 as="first" / as="last"。

布局模型

主布局模型：内联外壳布局。定义见 ../../../specs/maintainers/LayoutProtocol.md §12.4（源码参考：specs/maintainers/LayoutProtocol.md）。

• ButtonGroup 根层管理外壳圆角、背景、边框与裁剪；视觉 padding 转交给嵌入态 Button，确保每个单元格的 hover / 点击热区覆盖自身完整单元格。

• ButtonGroup 根层显式关闭 Auto Layout；Button 单元格之间的布局 gap 恒为 0，内容到内置分割线的视觉距离只由相邻 Button 的内侧 padding 表达。Button hover 盒必须与分割线边界连续。

• 如果消费方在 ButtonGroup 根层追加 padding（例如 class="p-40" 或内联 padding），ButtonGroup 会把根层 padding 映射为首尾单元格 hover 覆盖的扩展区域；hover 仍然按单元格独立响应，并被根层圆角裁剪。

• ButtonGroup 与 Button 相同的视觉规则统一使用 Button token：--snowui-button-padding-block / --snowui-button-padding-inline、--snowui-button-radius、--snowui-button-background、--snowui-button-color、--snowui-button-border-*、--snowui-button-font-size、--snowui-button-line-height。ButtonGroup 只保留分组专属的内侧间距、Separator 长度与外部 padding 扩展变量。

• Button 管理单元格内部 Icon / Text / Spinner 的 gap。

• 内置分割线不占布局、不通过 margin 表达间距；单元格到分割线的空间由嵌入态 Button 的单元格 padding 承担。

• 外侧 padding 是单元格内容到 ButtonGroup 边缘的距离，沿用 Button 的 padding-x；内侧 padding 是单元格内容到 Separator 的距离，使用 ButtonGroup 的 gap。

• 首单元格左侧使用外侧 padding，右侧使用内侧 padding；尾单元格右侧使用外侧 padding，左侧使用内侧 padding；中间单元格两侧都使用内侧 padding。多个单元格按 DOM 顺序自动应用。

• ButtonGroup 根元素默认 width: max-content 且 align-self: flex-start，避免放在 flex-col 这类父容器中被 align-items: stretch 横向撑大。

• 默认单元格保持 Hug 内容，不做均分拉伸。

• Hover 状态由内部每个 Button 单元格分别响应，ButtonGroup 外壳不做整块 hover 变色；单元格 hover 颜色规则与 Button 对应 variant 保持一致。

• Disabled 状态由 ButtonGroup 外壳统一应用 opacity: 0.2；内部继承 disabled 的嵌入态 Button 只保留禁用语义，不重复衰减透明度。

• 内容不使用三槽位语义；as="leading" / as="trailing" 只表示 ButtonGroup 作为外层宿主的配件角色，不改变 ButtonGroup 内部排列。