Toggle 切换

基于 reka-ui 的 Toggle 原语构建的新粗野主义风格切换按钮，支持按下状态。

预览

Preview

默认变体

轮廓变体

尺寸

禁用

加载中

安装

pnpm dlx brutx-vue@latest add toggle

用法

基础用法

<script setup>
import { ref } from 'vue'
import { Toggle } from 'brutx-ui-vue'
import { Bold, Italic, Underline } from '@lucide/vue'

const bold = ref(false)
const italic = ref(false)
const underline = ref(false)
</script>

<template>
    <div class="flex items-center gap-2">
        <Toggle v-model="bold" variant="default" size="default">
            <Bold class="h-4 w-4" />
        </Toggle>
        <Toggle v-model="italic" variant="default" size="default">
            <Italic class="h-4 w-4" />
        </Toggle>
        <Toggle v-model="underline" variant="default" size="default">
            <Underline class="h-4 w-4" />
        </Toggle>
    </div>
</template>

Loading 状态

通过 loading prop 显示加载指示器（Loader2 旋转图标），此时按钮会自动禁用并设置 aria-busy="true"，适合异步操作场景。loading 期间原插槽内容会被替换为旋转图标。

<script setup>
import { Toggle } from 'brutx-ui-vue'
import { Bold } from '@lucide/vue'
</script>

<template>
    <Toggle loading aria-label="加粗">
        <Bold class="h-4 w-4" />
    </Toggle>
</template>

无障碍标签

Toggle 不会自动生成默认 aria-label。当插槽内容仅为图标时，建议通过 ariaLabel prop 提供可读文本，以便屏幕阅读器正确朗读按钮用途。

<script setup>
import { ref } from 'vue'
import { Toggle } from 'brutx-ui-vue'
import { Bold } from '@lucide/vue'

const bold = ref(false)
</script>

<template>
    <Toggle v-model="bold" aria-label="加粗">
        <Bold class="h-4 w-4" />
    </Toggle>
</template>

变体

变体	说明
default	带背景和小阴影，按下时为主色背景
outline	透明带边框，按下时为辅助色背景

尺寸

尺寸	高度	最小宽度	字体大小
sm	h-8	min-w-8	text-xs
default	h-10	min-w-10	text-sm
lg	h-12	min-w-12	text-sm

API 参考

Toggle — 属性

名称	类型	默认值	说明
modelValue	boolean | undefined	—	当前按下状态，通过 v-model 受控绑定。
详情 声明类型 boolean | undefined 字面量 false true 默认值详情 未声明默认值 — 来源 Toggle.vue:13 packages/ui/src/components/toggle/Toggle.vue
variant	"default" | "outline" | undefined	"default"	设置 Toggle 的视觉变体。
详情 声明类型 NonNullable<"default" | "outline" | null | undefined> | undefined 字面量 "default" "outline" 默认值详情 声明 'default' 来源: packages/ui/src/components/toggle/Toggle.vue 解析值 "default" 来源 Toggle.vue:14 packages/ui/src/components/toggle/Toggle.vue
size	"default" | "lg" | "sm" | undefined	"default"	设置 Toggle 按钮的尺寸。
详情 声明类型 NonNullable<"default" | "lg" | "sm" | null | undefined> | undefined 字面量 "default" "lg" "sm" 默认值详情 声明 'default' 来源: packages/ui/src/components/toggle/Toggle.vue 解析值 "default" 来源 Toggle.vue:15 packages/ui/src/components/toggle/Toggle.vue
disabled	boolean | undefined	false	禁用按钮交互。
详情 声明类型 boolean | undefined 字面量 false true 默认值详情 声明 false 来源: packages/ui/src/components/toggle/Toggle.vue 解析值 false 来源 Toggle.vue:16 packages/ui/src/components/toggle/Toggle.vue
loading	boolean | undefined	false	显示加载指示器并禁用交互；加载时默认插槽内容被加载状态替代。
详情 声明类型 boolean | undefined 字面量 false true 默认值详情 声明 false 来源: packages/ui/src/components/toggle/Toggle.vue 解析值 false 来源 Toggle.vue:17 packages/ui/src/components/toggle/Toggle.vue
class	string | undefined	undefined	追加到 Toggle 根按钮的 CSS 类。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/toggle/Toggle.vue 解析值 undefined 来源 Toggle.vue:18 packages/ui/src/components/toggle/Toggle.vue
ariaLabel	string | undefined	undefined	设置 Toggle 的无障碍名称；图标按钮应提供此标签。
详情 声明类型 string | undefined 默认值详情 声明 undefined 来源: packages/ui/src/components/toggle/Toggle.vue 解析值 undefined 来源 Toggle.vue:20 packages/ui/src/components/toggle/Toggle.vue

Toggle — 事件

名称	签名或类型	说明
@update:modelValue	[value: boolean]	用户切换按下状态时发出新的布尔值。
详情 声明类型 [value: boolean] 字面量 false true 来源 Toggle.vue packages/ui/src/components/toggle/Toggle.vue

Toggle — 插槽

名称	签名或类型	说明
#default	{}	按钮中显示的文本、图标或其他内容；loading 为真时由加载指示器替代。
详情 声明类型 {} 来源 Toggle.vue packages/ui/src/components/toggle/Toggle.vue

可访问性

• 键盘操作：支持 Space / Enter 触发切换
• ARIA 属性：自动管理 aria-pressed 状态；loading 时设置 aria-busy="true"
• 无障碍标签：Toggle 不会自动生成默认 aria-label，当插槽内容仅为图标时，建议通过 ariaLabel prop 提供可读文本