BreezeUI
  • 简体中文

    • Checkbox 复选框

    用于在多个选项中选择一个或多个。基于 BrConfigProvider 实现全局主题配置。

    组件特性

    • ☑️ 单选和分组：支持单个复选框和 BrCheckboxGroup 多选组合。
    • 🔲 不确定状态：支持父级复选的半选状态。
    • 📏 多种尺寸：支持 xs、sm、md、lg、xl、2xl 尺寸规格。
    • ❌ 禁用状态：支持单个和分组模式的 disabled 属性。
    • ⚠️ 错误状态：支持 error 属性显示错误状态。
    • 🏷️ 自定义标签：通过插槽支持自定义标签内容。
    • 🎨 主题定制：基于 BrConfigProvider 支持全局主题配置和 TailwindCSS 局部覆盖。

    基础用法

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

const checked = ref(false)
</script>

<template>
  <div class="flex items-center space-x-2">
    <BrCheckbox id="terms" v-model="checked" label="Accept terms and conditions" />
  </div>
</template>

    复选框组

    使用 BrCheckboxGroup 来组合多个复选框。

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

const selected = ref(['apple'])
</script>

<template>
  <div class="space-y-4">
    <BrCheckboxGroup v-model="selected">
      <BrCheckbox value="apple" label="Apple" />
      <BrCheckbox value="banana" label="Banana" />
      <BrCheckbox value="cherry" label="Cherry" />
    </BrCheckboxGroup>
    
    <div class="text-sm text-muted-foreground">
      Selected: {{ selected }}
    </div>
  </div>
</template>

    不确定状态 (Indeterminate)

    indeterminate 状态用于复选框既非选中也非未选中的状态（例如：全选/半选）。

    <script setup lang="ts">
import { ref, watch } from 'vue'
import { BrCheckbox, BrCheckboxGroup } from '@breezeui/vue'

const checkAll = ref(false)
const indeterminate = ref(true)
const checkedCities = ref(['Shanghai', 'Beijing'])
const cities = ['Shanghai', 'Beijing', 'Guangzhou', 'Shenzhen']

const handleCheckAllChange = (val: boolean) => {
  indeterminate.value = false
  if (val) {
    checkedCities.value = [...cities]
  } else {
    checkedCities.value = []
  }
}

watch(checkedCities, (val) => {
  const checkedCount = val.length
  const citiesCount = cities.length
  checkAll.value = checkedCount === citiesCount
  indeterminate.value = checkedCount > 0 && checkedCount < citiesCount
})
</script>

<template>
  <div class="space-y-4">
    <BrCheckbox
      :model-value="checkAll"
      :indeterminate="indeterminate"
      @update:model-value="handleCheckAllChange"
    >
      Check all
    </BrCheckbox>
    
    <div class="ml-6">
      <BrCheckboxGroup v-model="checkedCities" class="flex flex-col gap-2">
        <BrCheckbox v-for="city in cities" :key="city" :value="city" :label="city" />
      </BrCheckboxGroup>
    </div>
  </div>
</template>

    尺寸

    我们提供了一组默认尺寸，你可以通过 size 属性来控制。

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

const checked = ref(true)
</script>

<template>
  <div class="flex flex-col gap-4">
    <div class="flex items-center gap-2">
      <BrCheckbox v-model="checked" size="xs" label="Extra Small (xs)" />
    </div>
    <div class="flex items-center gap-2">
      <BrCheckbox v-model="checked" size="sm" label="Small (sm)" />
    </div>
    <div class="flex items-center gap-2">
      <BrCheckbox v-model="checked" size="default" label="Default (md)" />
    </div>
    <div class="flex items-center gap-2">
      <BrCheckbox v-model="checked" size="lg" label="Large (lg)" />
    </div>
    <div class="flex items-center gap-2">
      <BrCheckbox v-model="checked" size="xl" label="Extra Large (xl)" />
    </div>
    <div class="flex items-center gap-2">
      <BrCheckbox v-model="checked" size="2xl" label="2X Large (2xl)" />
    </div>
  </div>
</template>

    禁用状态

    <script setup lang="ts">
import { BrCheckbox, BrCheckboxGroup } from '@breezeui/vue'
</script>

<template>
  <div class="space-y-4">
    <div class="flex items-center space-x-2">
      <BrCheckbox disabled label="Disabled Checkbox" />
    </div>
    <div class="flex items-center space-x-2">
      <BrCheckbox disabled :model-value="true" label="Disabled Checked" />
    </div>
    
    <div class="space-y-2">
      <p class="text-sm font-medium">Disabled Group</p>
      <BrCheckboxGroup disabled :model-value="['apple']">
        <BrCheckbox value="apple" label="Apple" />
        <BrCheckbox value="banana" label="Banana" />
      </BrCheckboxGroup>
    </div>
  </div>
</template>

    主题定制

    全局定制 (BrConfigProvider)

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

    <template>
  <BrConfigProvider :theme="{ primary: '#10B981', radius: 0.5 }">
    <BrCheckbox v-model="checked" label="Custom Theme" />
  </BrConfigProvider>
</template>

    局部定制 (TailwindCSS)

    你可以直接在包装器上使用 TailwindCSS 工具类覆盖样式。

    <template>
  <BrCheckbox class="mb-4" label="Margin Bottom" />
</template>

    API

    BrCheckbox

    Props

    名称类型默认值说明
    modelValueboolean | string | numberundefined绑定值
    valuestring | number | booleanundefined复选框的值（在组中使用）
    disabledbooleanfalse是否禁用
    indeterminatebooleanfalse是否处于不确定状态
    labelstringundefined标签文本
    idstringundefinedInput id
    namestringundefinedInput name
    requiredbooleanfalse是否必填
    errorbooleanfalse是否处于错误状态
    size'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | 'default''default'尺寸

    Emits

    名称说明参数
    update:modelValue更新模型值(value: boolean | string | number)
    change变更事件(value: boolean | string | number)

    Slots

    名称说明
    default标签内容
    icon自定义图标插槽

    BrCheckboxGroup

    Props

    名称类型默认值说明
    modelValue(string | number)[][]绑定值数组
    disabledbooleanfalse是否禁用组内所有复选框
    size'sm' | 'default' | 'lg''default'组内所有复选框的尺寸
    namestringundefined所有复选框的 name 属性

    Emits

    名称说明参数
    update:modelValue更新模型值(value: (string | number)[])
    change变更事件(value: (string | number)[])