Toggle Group 切换组
基于 reka-ui 的 ToggleGroup 原语构建的新粗野主义风格切换按钮组，支持单选或多选。变体和尺寸通过 provide/inject 下发给所有子项，支持水平和垂直排列方向。
预览
单选
多选
轮廓变体
尺寸
方向
禁用
安装
pnpm dlx brutx-vue@latest add toggle-group用法
单选
type="single" 时只能选中一个按钮，modelValue 为 string。
<script setup>
import { ref } from 'vue'
import { ToggleGroup, ToggleGroupItem } from 'brutx-ui-vue'
import { AlignLeft, AlignCenter, AlignRight } from '@lucide/vue'
const align = ref('left')
</script>
<template>
<ToggleGroup type="single" v-model="align" variant="default">
<ToggleGroupItem value="left">
<AlignLeft class="h-4 w-4" />
</ToggleGroupItem>
<ToggleGroupItem value="center">
<AlignCenter class="h-4 w-4" />
</ToggleGroupItem>
<ToggleGroupItem value="right">
<AlignRight class="h-4 w-4" />
</ToggleGroupItem>
</ToggleGroup>
</template>多选
type="multiple" 时可以同时选中多个按钮，modelValue 为 string[]。
<script setup>
import { ref } from 'vue'
import { ToggleGroup, ToggleGroupItem } from 'brutx-ui-vue'
import { Bold, Italic, Underline } from '@lucide/vue'
const styles = ref([])
</script>
<template>
<ToggleGroup type="multiple" v-model="styles" variant="default">
<ToggleGroupItem value="bold">
<Bold class="h-4 w-4" />
</ToggleGroupItem>
<ToggleGroupItem value="italic">
<Italic class="h-4 w-4" />
</ToggleGroupItem>
<ToggleGroupItem value="underline">
<Underline class="h-4 w-4" />
</ToggleGroupItem>
</ToggleGroup>
</template>排列方向
通过 orientation 属性控制排列方向。vertical 时容器使用 flex-col，并透传给 reka-ui 原语设置 aria-orientation。
<script setup>
import { ref } from 'vue'
import { ToggleGroup, ToggleGroupItem } from 'brutx-ui-vue'
const styles = ref([])
</script>
<template>
<ToggleGroup type="multiple" v-model="styles" orientation="vertical">
<ToggleGroupItem value="bold">加粗</ToggleGroupItem>
<ToggleGroupItem value="italic">斜体</ToggleGroupItem>
<ToggleGroupItem value="underline">下划线</ToggleGroupItem>
</ToggleGroup>
</template>变体
| 变体 | 说明 |
|---|---|
default | 带背景和小阴影，按下时为主色背景 |
outline | 透明带边框，按下时为辅助色背景 |
变体在 ToggleGroup 上设置，会通过 provide/inject 下发给所有 ToggleGroupItem，子项也可单独覆盖。
尺寸
| 尺寸 | 高度 | 最小宽度 | 字体大小 |
|---|---|---|---|
sm | h-8 | min-w-8 | text-xs |
default | h-10 | min-w-10 | text-sm |
lg | h-12 | min-w-12 | text-sm |
子组件
| 组件 | 说明 |
|---|---|
ToggleGroup | 根组件，管理选中状态和组配置 |
ToggleGroupItem | 子项按钮，继承父组件的变体和尺寸 |
API 参考
ToggleGroup
| 名称 | 类型 | 默认值 | 说明 |
|---|---|---|---|
type | "single" | "multiple" | undefined | "single" | 选择单选或多选模式；单选值为字符串，多选值为字符串数组。 |
详情声明类型"single" | "multiple" | undefined 字面量
默认值详情
来源packages/ui/src/components/toggle-group/ToggleGroup.vue | |||
modelValue | string | string[] | undefined | undefined | 当前选中值，支持 v-model；值的形状由 type 决定。 |
详情声明类型string | string[] | undefined 默认值详情
来源packages/ui/src/components/toggle-group/ToggleGroup.vue | |||
variant | "default" | "outline" | undefined | "default" | 选择传递给未单独覆盖子项的默认视觉变体。 |
详情声明类型NonNullable<"default" | "outline" | null | undefined> | undefined 字面量
默认值详情
来源packages/ui/src/components/toggle-group/ToggleGroup.vue | |||
size | "default" | "lg" | "sm" | undefined | "default" | 选择传递给未单独覆盖子项的默认尺寸。 |
详情声明类型NonNullable<"default" | "lg" | "sm" | null | undefined> | undefined 字面量
默认值详情
来源packages/ui/src/components/toggle-group/ToggleGroup.vue | |||
orientation | "vertical" | "horizontal" | undefined | "horizontal" | 选择水平或垂直排列；垂直模式使用纵向 flex 容器并传递给 Reka UI 原语。 |
详情声明类型"vertical" | "horizontal" | undefined 字面量
默认值详情
来源packages/ui/src/components/toggle-group/ToggleGroup.vue | |||
disabled | boolean | undefined | false | 禁用整个切换组并向子项提供禁用状态。 |
详情声明类型boolean | undefined 字面量
默认值详情
来源packages/ui/src/components/toggle-group/ToggleGroup.vue | |||
class | string | undefined | undefined | 追加到 ToggleGroup 根容器的自定义 CSS 类。 |
详情声明类型string | undefined 默认值详情
来源packages/ui/src/components/toggle-group/ToggleGroup.vue | |||
| 名称 | 签名或类型 | 说明 |
|---|---|---|
@update:modelValue | [value: string | string[]] | 底层切换组更新值时发出；单选未选中时归一化为空字符串，多选未选中时归一化为空数组。 |
详情声明类型[value: string | string[]] 来源packages/ui/src/components/toggle-group/ToggleGroup.vue | ||
| 名称 | 签名或类型 | 说明 |
|---|---|---|
#default | {} | 放置 ToggleGroupItem 子项。 |
详情声明类型{}来源packages/ui/src/components/toggle-group/ToggleGroup.vue | ||
ToggleGroupItem
| 名称 | 类型 | 默认值 | 说明 |
|---|---|---|---|
value必填 | string | — | 该切换项对应的唯一字符串值。 |
详情声明类型string 默认值详情
来源packages/ui/src/components/toggle-group/ToggleGroupItem.vue | |||
variant | "default" | "outline" | undefined | undefined | 覆盖父级 ToggleGroup 的变体；未设置时继承父级值，再回退到 default。 |
详情声明类型NonNullable<"default" | "outline" | null | undefined> | undefined 字面量
默认值详情
来源packages/ui/src/components/toggle-group/ToggleGroupItem.vue | |||
size | "default" | "lg" | "sm" | undefined | undefined | 覆盖父级 ToggleGroup 的尺寸；未设置时继承父级值，再回退到 default。 |
详情声明类型NonNullable<"default" | "lg" | "sm" | null | undefined> | undefined 字面量
默认值详情
来源packages/ui/src/components/toggle-group/ToggleGroupItem.vue | |||
disabled | boolean | undefined | false | 禁用当前项；最终禁用状态为自身与父级 ToggleGroup disabled 的逻辑或。 |
详情声明类型boolean | undefined 字面量
默认值详情
来源packages/ui/src/components/toggle-group/ToggleGroupItem.vue | |||
class | string | undefined | undefined | 追加到 ToggleGroupItem 按钮元素的自定义 CSS 类。 |
详情声明类型string | undefined 默认值详情
来源packages/ui/src/components/toggle-group/ToggleGroupItem.vue | |||
| 名称 | 签名或类型 | 说明 |
|---|---|---|
#default | {} | 呈现按钮项的图标、文本或其他内容。 |
详情声明类型{}来源packages/ui/src/components/toggle-group/ToggleGroupItem.vue | ||
可访问性
- ARIA 属性：自动管理
aria-pressed状态，vertical方向时设置aria-orientation="vertical" - 键盘操作：支持方向键在组内导航，
Space/Enter切换选中状态