Toggle 切换按钮

按钮式切换控件，允许用户在按下（激活）和未按下（非激活）状态之间切换。与 BrSwitch（滑块式开关）不同，BrToggle 是扁平按钮样式，通过背景色/颜色的变化来指示激活状态。

组件特性

🔄 四种变体：支持 outline（默认）、solid、soft、ghost 四种视觉变体。
🌈 多种颜色：支持 default、primary、secondary、success、warning、danger、info、carbon 等颜色主题。
📏 多种尺寸：支持 xs、sm、md、lg、xl、2xl、default 尺寸规格。
🖼️ 图标支持：通过 prefix 和 suffix 插槽支持前后图标组合。
⏳ 加载状态：支持 loading 属性显示加载动画。
❌ 禁用状态：支持 disabled 属性禁用切换按钮。
📝 只读状态：支持 readonly 属性设置为只读。
🎨 主题定制：基于 BrConfigProvider 支持全局主题配置和 TailwindCSS 局部覆盖。

基础用法

<script setup lang="ts">
import { ref } from 'vue'
import { BrToggle } from '@breezeui/vue'

const active = ref(false)
</script>

<template>
  <div class="flex items-center space-x-4">
    <BrToggle v-model="active">Toggle Button</BrToggle>
    <span class="text-sm text-muted-foreground">State: {{ active ? 'Pressed' : 'Unpressed' }}</span>
  </div>
</template>

变体样式

Toggle 支持四种视觉变体：outline（默认）、solid、soft 和 ghost。

<script setup lang="ts">
import { ref } from 'vue'
import { BrToggle, BrFlex } from '@breezeui/vue'

const solid = ref(true)
const outline = ref(false)
const soft = ref(true)
const ghost = ref(false)
</script>

<template>
  <BrFlex gap="3" wrap>
    <BrToggle v-model="solid" variant="solid">Solid</BrToggle>
    <BrToggle v-model="outline" variant="outline">Outline</BrToggle>
    <BrToggle v-model="soft" variant="soft">Soft</BrToggle>
    <BrToggle v-model="ghost" variant="ghost">Ghost</BrToggle>
  </BrFlex>
</template>

颜色

使用 color 属性设置切换按钮的颜色主题。

<script setup lang="ts">
import { ref } from 'vue'
import { BrToggle, BrFlex } from '@breezeui/vue'

const states = ref<Record<string, boolean>>({
  default: false,
  primary: true,
  secondary: false,
  success: false,
  warning: false,
  danger: false,
  info: false,
})
</script>

<template>
  <BrFlex gap="3" wrap>
    <BrToggle v-model="states.default" color="default">Default</BrToggle>
    <BrToggle v-model="states.primary" color="primary">Primary</BrToggle>
    <BrToggle v-model="states.secondary" color="secondary">Secondary</BrToggle>
    <BrToggle v-model="states.success" color="success">Success</BrToggle>
    <BrToggle v-model="states.warning" color="warning">Warning</BrToggle>
    <BrToggle v-model="states.danger" color="danger">Danger</BrToggle>
    <BrToggle v-model="states.info" color="info">Info</BrToggle>
  </BrFlex>
</template>

尺寸

使用 size 属性控制切换按钮的大小。

<script setup lang="ts">
import { ref } from 'vue'
import { BrToggle, BrFlex } from '@breezeui/vue'

const states = ref<Record<string, boolean>>({
  xs: false,
  sm: true,
  md: false,
  lg: false,
  xl: false,
})
</script>

<template>
  <BrFlex align="center" gap="3" wrap>
    <BrToggle v-model="states.xs" size="xs">XS</BrToggle>
    <BrToggle v-model="states.sm" size="sm">Small</BrToggle>
    <BrToggle v-model="states.md" size="md">Medium</BrToggle>
    <BrToggle v-model="states.lg" size="lg">Large</BrToggle>
    <BrToggle v-model="states.xl" size="xl">Extra Large</BrToggle>
  </BrFlex>
</template>

带图标

Toggle 支持 prefix 和 suffix 插槽，用于放置图标等丰富内容。

<script setup lang="ts">
import { ref } from 'vue'
import { BrToggle, BrFlex } from '@breezeui/vue'
import { Bold, Italic, Underline, Star } from 'lucide-vue-next'

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

<template>
  <BrFlex gap="3" wrap>
    <BrToggle v-model="bold" variant="outline">
      <template #prefix><Bold class="h-4 w-4" /></template>
      Bold
    </BrToggle>
    <BrToggle v-model="italic" variant="outline">
      <template #prefix><Italic class="h-4 w-4" /></template>
      Italic
    </BrToggle>
    <BrToggle v-model="underline" variant="outline">
      <template #prefix><Underline class="h-4 w-4" /></template>
      Underline
    </BrToggle>
    <BrToggle v-model="starred" color="warning" variant="soft">
      <template #suffix><Star class="h-4 w-4" /></template>
      Favorite
    </BrToggle>
  </BrFlex>
</template>

工具栏示例

常见场景：工具栏中包含多个切换按钮，用于格式化选项。

<script setup lang="ts">
import { ref } from 'vue'
import { BrToggle } from '@breezeui/vue'
import { Bold, Italic, Underline, AlignLeft, AlignCenter, AlignRight } from 'lucide-vue-next'

const bold = ref(false)
const italic = ref(false)
const underline = ref(false)
const alignLeft = ref(true)
const alignCenter = ref(false)
const alignRight = ref(false)
</script>

<template>
  <div class="border border-border rounded-lg p-2 inline-flex items-center gap-1">
    <BrToggle v-model="bold" variant="ghost" size="sm">
      <Bold class="h-4 w-4" />
    </BrToggle>
    <BrToggle v-model="italic" variant="ghost" size="sm">
      <Italic class="h-4 w-4" />
    </BrToggle>
    <BrToggle v-model="underline" variant="ghost" size="sm">
      <Underline class="h-4 w-4" />
    </BrToggle>
    <div class="w-px h-6 bg-border mx-1" />
    <BrToggle v-model="alignLeft" variant="ghost" size="sm">
      <AlignLeft class="h-4 w-4" />
    </BrToggle>
    <BrToggle v-model="alignCenter" variant="ghost" size="sm">
      <AlignCenter class="h-4 w-4" />
    </BrToggle>
    <BrToggle v-model="alignRight" variant="ghost" size="sm">
      <AlignRight class="h-4 w-4" />
    </BrToggle>
  </div>
</template>

禁用状态

设置 disabled 属性以禁用切换按钮。

<script setup lang="ts">
import { ref } from 'vue'
import { BrToggle } from '@breezeui/vue'

const active = ref(true)
</script>

<template>
  <div class="flex items-center space-x-4">
    <BrToggle v-model="active" disabled>Disabled (Active)</BrToggle>
    <BrToggle :model-value="false" disabled>Disabled (Inactive)</BrToggle>
  </div>
</template>

加载状态

设置 loading 属性显示加载动画。加载期间切换按钮将被禁用。

<script setup lang="ts">
import { ref } from 'vue'
import { BrToggle } from '@breezeui/vue'

const active = ref(false)
</script>

<template>
  <div class="flex items-center space-x-4">
    <BrToggle v-model="active" loading>Loading</BrToggle>
  </div>
</template>

主题定制

全局定制（BrConfigProvider）

通过 BrConfigProvider 的 theme 属性覆盖默认 CSS 变量。

<template>
  <BrConfigProvider :theme="{ primary: '#8b5cf6' }">
    <BrToggle v-model="active" color="primary">主题切换</BrToggle>
  </BrConfigProvider>
</template>

局部定制（TailwindCSS）

使用 TailwindCSS 工具类直接覆盖样式。

<template>
  <BrToggle v-model="active" class="rounded-full">圆形切换</BrToggle>
</template>

Toggle 与 Switch 的区别

特性	BrToggle	BrSwitch
样式	按钮式（扁平）	滑块式（带滑块）
视觉提示	背景色/颜色变化	滑块左右滑动
适用场景	工具栏操作、筛选器	设置选项、开/关
图标支持	prefix/suffix 插槽	thumb 插槽

API

Props

名称	类型	默认值	说明
modelValue	`boolean`	`undefined`	按下状态（v-model）
defaultValue	`boolean`	`false`	非受控模式下的默认按下状态
variant	`'solid' \| 'outline' \| 'soft' \| 'ghost'`	`'outline'`	视觉变体
color	`'default' \| 'primary' \| 'secondary' \| 'success' \| 'warning' \| 'danger' \| 'info' \| 'carbon'`	`'default'`	颜色主题
size	`'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl' \| 'default'`	`'default'`	切换按钮尺寸
disabled	`boolean`	`false`	是否禁用
loading	`boolean`	`false`	是否显示加载状态
readonly	`boolean`	`false`	是否只读
type	`'button' \| 'submit' \| 'reset'`	`'button'`	原生按钮类型
class	`any`	-	自定义 CSS 类名

Emits

名称	说明	参数
update:modelValue	按下状态变更时触发	`(value: boolean)`
change	按下状态变更时触发	`(value: boolean)`

Slots

名称	说明
default	默认内容（文字/图标）
prefix	前置内容
suffix	后置内容

#Toggle 切换按钮

#组件特性

#基础用法

#变体样式

#颜色

#尺寸

#带图标

#工具栏示例

#禁用状态

#加载状态

#主题定制

#全局定制（BrConfigProvider）

#局部定制（TailwindCSS）

#Toggle 与 Switch 的区别

#API

#Props

#Emits

#Slots