安装

pnpm dlx shadcn-vue@latest add button-group

用法

<script setup lang="ts">
import {
  ButtonGroup,
  ButtonGroupSeparator,
  ButtonGroupText,
} from '@/components/ui/button-group'
</script>

<template>
  <ButtonGroup>
    <Button>Button 1</Button>
    <Button>Button 2</Button>
  </ButtonGroup>
</template>

访问性

• ButtonGroup 组件的 role 属性设置为 group。
• 使用 Tab 键在按钮组之间导航。
• 使用 aria-label 或 aria-labelledby 给按钮组添加标签。

<template>
  <ButtonGroup aria-label="Button group">
    <Button>Button 1</Button>
    <Button>Button 2</Button>
  </ButtonGroup>
</template>

ButtonGroup 与 ToggleGroup

• 当您想要将执行操作的按钮分组时使用 ButtonGroup 组件。
• 当您想要将切换状态的按钮分组时使用 ToggleGroup 组件。

示例

方向

设置 orientation 属性可以更改按钮组的布局。

尺寸

使用单个按钮的 size 属性控制按钮大小。

嵌套

<ButtonGroup> 组件可创建具有间距的按钮组。

分隔符

ButtonGroupSeparator 组件在组内可视化分隔按钮。

具有 outline 变体的按钮不需要分隔符，因为它们已经有边框。对其他变体，建议使用分隔符以提升视觉层次。

拆分

通过添加由 ButtonGroupSeparator 分隔的两个按钮来创建拆分按钮组。

输入

将 Input 组件与按钮包裹。

输入组

包裹 InputGroup 组件以创建更复杂的输入布局。

下拉菜单

使用 DropdownMenu 组件创建拆分按钮组。

选择

与 Select 组件配合使用。

弹出

与 Popover 组件配合使用。

API 参考

ButtonGroup

ButtonGroup 组件是一个容器，用于将相关按钮组合在一起并保持一致的样式。

prop	type	default
orientation	"horizontal" | "vertical"	"horizontal"

<template>
  <ButtonGroup>
    <Button>Button 1</Button>
    <Button>Button 2</Button>
  </ButtonGroup>
</template>

嵌套多个按钮组可创建带间距的复杂布局。更多信息请参阅 [嵌套] 示例。

<template>
  <ButtonGroup>
    <ButtonGroup />
    <ButtonGroup />
  </ButtonGroup>
</template>

ButtonGroupSeparator

ButtonGroupSeparator 组件在组内可视化分隔按钮。

prop	type	default
orientation	"horizontal" | "vertical"	"vertical"

<template>
  <ButtonGroup>
    <Button>Button 1</Button>
    <ButtonGroupSeparator />
    <Button>Button 2</Button>
  </ButtonGroup>
</template>

ButtonGroupText

使用此组件在按钮组内部显示文本。

prop	type	default
as-child	boolean	false

<template>
  <ButtonGroup>
    <ButtonGroupText>Text</ButtonGroupText>
    <Button>Button</Button>
  </ButtonGroup>
</template>

使用 as-child 属性将自定义组件渲染为文本，例如标签。

<script setup lang="ts">
import { ButtonGroupText } from '@/components/ui/button-group'
import { Label } from '@/components/ui/label'
</script>

<template>
  <ButtonGroup>
    <ButtonGroupText as-child>
      <Label html-for="name">Text</Label>
    </ButtonGroupText>
    <Input id="name" placeholder="Type something here..." />
  </ButtonGroup>
</template>