TechUI Docs

简中

EN

简中

EN

主题

复选框 ​

TuiCheckbox 用于在多个备选项中进行多选。 它与单选框（Radio）共享相似的外观系统，但其绑定值是数组。支持数量限制、按钮样式、卡片样式以及高度自定义的插槽内容。

基础用法 ​

数据驱动渲染 (Options) ​

通过 options 属性传入配置数组。

  • modelValue: 必须绑定一个数组。
html
<script setup>
import { ref } from 'vue';

const checkedList = ref(['A', 'B']);
const options = [
  { label: '选项 A', value: 'A' },
  { label: '选项 B', value: 'B' },
  { label: '禁用项', value: 'C', disabled: true }
];
</script>

<template>
  <TuiCheckbox v-model="checkedList" :options="options" />
</template>

插槽自定义渲染 (Slot) ​

使用 <TuiCheckboxItem> 子组件构建。

html
<template>
  <TuiCheckbox v-model="checkedList">
    <TuiCheckboxItem value="apple">苹果</TuiCheckboxItem>
    <TuiCheckboxItem value="banana">香蕉</TuiCheckboxItem>
  </TuiCheckbox>
</template>

外观风格 ​

通过 appearance 属性切换风格。

简约风格 (Simple) ​

默认风格，标准的方形勾选框。

按钮风格 (Button) ​

实心按钮样式。选中时背景色填充。

  • separable: 设置为 true 可让按钮之间产生间距。
html
<template>
  <TuiCheckbox appearance="button" v-model="vals" :options="opts" />
  
  <TuiCheckbox appearance="button" separable v-model="vals" :options="opts" />
</template>

卡片风格 (ButtonPlain) ​

描边卡片样式。选中时边框高亮。

html
<TuiCheckbox appearance="buttonPlain" v-model="vals" :options="opts" />

布局与方向 ​

  • direction: 'v' (垂直) / 'h' (水平)。
  • textDirection: 'v' 可让选项文字竖直排列。
html
<TuiCheckbox direction="v" :options="options" />

数量限制 ​

通过 max 属性可以限制用户最多选择的项目数量。 当达到最大限制时，未选中的选项将自动变为禁用状态。

html
<template>
  <TuiCheckbox 
    :max="2" 
    v-model="checkedCities" 
    :options="cities" 
  />
</template>

图标定制 ​

与 Radio 类似，支持自定义图标状态切换。 传入数组 ['未选图标', '选中图标']。

html
<script setup>
const iconOpts = [
  { label: '收藏', value: 1, icon: ['tui-icon ti-star', 'tui-icon tis-star'] },
  { label: '点赞', value: 2, icon: ['tui-icon ti-thumb-up', 'tui-icon tis-thumb-up'] }
];
</script>

<template>
  <TuiCheckbox appearance="buttonPlain" :options="iconOpts" />
</template>

高级定制 ​

案例：主题色板选择器 ​

利用 defaultIcon="false" 隐藏默认复选框，配合插槽实现完全自定义的交互界面。

html
<template>
  <TuiCheckbox v-model="selectedThemes" :defaultIcon="false" class="theme-checkbox">
    <TuiCheckboxItem 
      v-for="item in themeOptions" 
      :key="item.value" 
      :value="item.value"
      class="theme-item"
    >
      <div class="color-view">
        <i class="tui-icon ti-check check-mark"></i>
        <div class="color-stripe" :style="{ background: item.color1 }"></div>
        <div class="color-stripe" :style="{ background: item.color2 }"></div>
      </div>
    </TuiCheckboxItem>
  </TuiCheckbox>
</template>

<style lang="less" scoped>
.theme-checkbox {
  .theme-item {
    margin-right: 10px;
    // 选中状态样式
    &.is-active {
      .check-mark { opacity: 1; transform: translate(-50%, -50%) scale(1); }
    }
    
    .color-view {
      position: relative; width: 40px; height: 40px; border-radius: 6px; overflow: hidden;
      .color-stripe { height: 50%; width: 100%; }
      .check-mark {
        position: absolute; left: 50%; top: 50%; color: #fff; opacity: 0;
        transform: translate(-50%, -50%) scale(0.5); transition: all 0.2s;
        text-shadow: 0 1px 2px rgba(0,0,0,0.3);
      }
    }
  }
}
</style>

API 参考 ​

TuiCheckbox Props ​

属性名类型默认值说明
modelValueArray-必填。绑定值数组。
optionsArray[]数据源。
maxNumber-最大可选数量。
appearanceString'simple'外观风格。可选：simple, button, buttonPlain。
directionString'h'排列方向。可选：h, v。
sizeString'default'尺寸。可选：large, default, small。
defaultIconBooleantrue是否显示默认复选框图标。
separableBooleanfalse按钮模式下是否分离。
alignStringnull对齐方式。
textDirectionStringnull文本排列方向。
itemMaxWidthNumber/String-选项最大宽度。
disabledBooleanfalse全局禁用。
classNameString-自定义类名。

TuiCheckbox Events ​

事件名说明回调参数
update:modelValue绑定值变化时触发。(value: Array)
change选中状态改变时触发。(value: Array)

TuiCheckboxItem Props ​

属性名类型默认值说明
valueString/Number/BooleanRequired选项的值。
iconString/Arraynull图标配置。
disabledBooleanfalse是否禁用该项。