TinyVue Checkbox复选框组件使用指南

如果超人不会飞2026-06-10 10:09

TinyVue Checkbox 复选框组件使用指南

组件介绍

Checkbox（复选框）是表单中常用的选择组件，用于在一组选项中进行多选。TinyVue 提供了完整的复选框体系，包括 Checkbox（复选框）、CheckboxGroup（复选框组）和 CheckboxButton（按钮式复选框）三个组件，支持配置式渲染、全选/半选、可选数量限制、过滤器模式、垂直布局、自定义颜色等丰富特性。

引入方式：

js 复制代码 
import { TinyCheckbox, TinyCheckboxGroup, TinyCheckboxButton } from '@opentiny/vue'

基本用法

通过 v-model 双向绑定选中状态（boolean），name 设置原生属性：

vue 复制代码 
<template>
  <tiny-checkbox v-model="checked" name="agree">同意协议</tiny-checkbox>
</template>

<script setup>
import { ref } from 'vue'
import { TinyCheckbox } from '@opentiny/vue'

const checked = ref(true)
</script>

复选框组

CheckboxGroup 将多个 Checkbox 管理为一组，通过 v-model 绑定选中值数组。每个 Checkbox 的 label 与数组中的值对应，存在则为选中状态：

vue 复制代码 
<template>
  <tiny-checkbox-group v-model="checked">
    <tiny-checkbox label="复选框 1"></tiny-checkbox>
    <tiny-checkbox label="复选框 2"></tiny-checkbox>
    <tiny-checkbox label="复选框 3"></tiny-checkbox>
  </tiny-checkbox-group>
</template>

<script setup>
import { ref } from 'vue'
import { TinyCheckbox, TinyCheckboxGroup } from '@opentiny/vue'

const checked = ref(['复选框 1', '复选框 2'])
</script>

按钮式复选框

通过 CheckboxButton 以按钮形式展示复选框，用法与 Checkbox 相似，需在 CheckboxGroup 中使用：

vue 复制代码 
<template>
  <tiny-checkbox-group v-model="checked">
    <tiny-checkbox-button label="复选框 1"></tiny-checkbox-button>
    <tiny-checkbox-button label="复选框 2"></tiny-checkbox-button>
    <tiny-checkbox-button label="复选框 3"></tiny-checkbox-button>
  </tiny-checkbox-group>
</template>

<script setup>
import { ref } from 'vue'
import { TinyCheckboxButton, TinyCheckboxGroup } from '@opentiny/vue'

const checked = ref(['复选框 1'])
</script>

配置式复选框组

通过 options 属性配置复选框组子项，无需在标签中手动插入 Checkbox 元素。配合 type 属性可切换为按钮形式：

vue 复制代码 
<template>
  <!-- 普通复选框形式 -->
  <tiny-checkbox-group v-model="checkList" type="checkbox" :options="options"></tiny-checkbox-group>

  <!-- 按钮形式 -->
  <tiny-checkbox-group v-model="checkList" type="button" :options="options"></tiny-checkbox-group>
</template>

<script setup>
import { ref } from 'vue'
import { TinyCheckboxGroup } from '@opentiny/vue'

const checkList = ref(['A'])
const options = ref([
  { label: 'A', text: '很好' },
  { label: 'B', text: '一般' },
  { label: 'C', text: '较差', disabled: true }
])
</script>

options 配置项类型 ICheckboxGroupOptions：

字段 类型 说明
label string 选中时对应的值
text string 描述文本
disabled boolean 是否禁用
checked boolean 是否默认选中
events { click?, change? } 原生事件回调

描述文本

复选框的描述文本有三种提供方式，优先级依次为：默认插槽 > text 属性 > label 属性：

vue 复制代码 
<template>
  <tiny-checkbox-group v-model="checked">
    <!-- 使用 label 作为描述 -->
    <tiny-checkbox label="复选框 1"></tiny-checkbox>

    <!-- 使用 text 属性覆盖 label 显示 -->
    <tiny-checkbox label="复选框 2" text="自定义文本"></tiny-checkbox>

    <!-- 使用默认插槽，优先级最高 -->
    <tiny-checkbox label="复选框 3">插槽内容</tiny-checkbox>
  </tiny-checkbox-group>
</template>

<script setup>
import { ref } from 'vue'
import { TinyCheckbox, TinyCheckboxGroup } from '@opentiny/vue'

const checked = ref(['复选框 1', '复选框 2', '复选框 3'])
</script>

禁用状态

通过 disabled 属性禁用单个复选框或整组：

vue 复制代码 
<template>
  <!-- 禁用单个 -->
  <tiny-checkbox v-model="checked" disabled>禁用复选框</tiny-checkbox>

  <!-- 禁用整组 -->
  <tiny-checkbox-group v-model="checked" disabled>
    <tiny-checkbox label="选项 1"></tiny-checkbox>
    <tiny-checkbox label="选项 2"></tiny-checkbox>
  </tiny-checkbox-group>
</template>

<script setup>
import { ref } from 'vue'
import { TinyCheckbox, TinyCheckboxGroup } from '@opentiny/vue'

const checked = ref(true)
</script>

全选与半选

通过 indeterminate 属性设置半选状态（只负责样式控制），常与全选逻辑配合使用：

vue 复制代码 
<template>
  <div>
    <tiny-checkbox :indeterminate="isIndeterminate" v-model="checkAll">全选</tiny-checkbox>
    <tiny-checkbox-group v-model="checkboxGroup">
      <tiny-checkbox v-for="(city, index) in cities" :label="city" :key="index">
        {{ city }}
      </tiny-checkbox>
    </tiny-checkbox-group>
  </div>
</template>

<script setup>
import { ref, computed } from 'vue'
import { TinyCheckbox, TinyCheckboxGroup } from '@opentiny/vue'

const checkboxGroup = ref(['北京'])
const cities = ref(['上海', '北京', '广州', '深圳'])

// 半选状态：部分选中
const isIndeterminate = computed(() => {
  return checkboxGroup.value.length > 0 && checkboxGroup.value.length !== cities.value.length
})

// 全选状态：双向计算属性
const checkAll = computed({
  get() {
    return checkboxGroup.value.length === cities.value.length
  },
  set(val) {
    checkboxGroup.value = val ? [...cities.value] : []
  }
})
</script>

可选数量限制

在 CheckboxGroup 上通过 min 和 max 属性限制可勾选项目的最小和最大数量：

vue 复制代码 
<template>
  <tiny-checkbox-group v-model="checkboxGroup" :min="1" :max="2">
    <tiny-checkbox v-for="city in cities" :label="city" :key="city">
      {{ city }}
    </tiny-checkbox>
  </tiny-checkbox-group>
</template>

<script setup>
import { ref } from 'vue'
import { TinyCheckbox, TinyCheckboxGroup } from '@opentiny/vue'

const checkboxGroup = ref(['上海', '北京'])
const cities = ref(['上海', '北京', '广州', '深圳'])
</script>

当已选数量达到 max 时，未选的复选框自动禁用；当已选数量等于 min 时，已选的复选框不可取消。

默认勾选

CheckboxGroup 的 v-model 可以配置默认选中项，Checkbox 的 checked 属性同样可以配置默认选中：

vue 复制代码 
<template>
  <!-- 通过 v-model 设置默认选中 -->
  <tiny-checkbox-group v-model="checked">
    <tiny-checkbox label="A"></tiny-checkbox>
    <tiny-checkbox label="B"></tiny-checkbox>
  </tiny-checkbox-group>
</template>

<script setup>
import { ref } from 'vue'
import { TinyCheckbox, TinyCheckboxGroup } from '@opentiny/vue'

const checked = ref(['A'])  // A 默认选中
</script>

选中/未选中值

通过 true-label 和 false-label 设置选中与未选中时绑定的值，而非默认的 true/false：

vue 复制代码 
<template>
  <tiny-checkbox
    v-model="checked"
    text="状态切换"
    true-label="已启用"
    false-label="已禁用"
  ></tiny-checkbox>
</template>

<script setup>
import { ref } from 'vue'
import { TinyCheckbox } from '@opentiny/vue'

const checked = ref('已禁用')
</script>

尺寸

当复选框为按钮形式时，通过 CheckboxGroup 的 size 属性设置尺寸，可选值：medium、small、mini：

vue 复制代码 
<template>
  <div>
    <tiny-checkbox-group v-model="checkboxGroup" size="medium">
      <tiny-checkbox-button v-for="city in cities" :label="city" :key="city">
        {{ city }}
      </tiny-checkbox-button>
    </tiny-checkbox-group>

    <tiny-checkbox-group v-model="checkboxGroup" size="small">
      <tiny-checkbox-button v-for="city in cities" :label="city" :key="city">
        {{ city }}
      </tiny-checkbox-button>
    </tiny-checkbox-group>

    <tiny-checkbox-group v-model="checkboxGroup" size="mini">
      <tiny-checkbox-button v-for="city in cities" :label="city" :key="city">
        {{ city }}
      </tiny-checkbox-button>
    </tiny-checkbox-group>
  </div>
</template>

<script setup>
import { ref } from 'vue'
import { TinyCheckboxButton, TinyCheckboxGroup } from '@opentiny/vue'

const cities = ref(['上海', '北京', '广州', '深圳'])
const checkboxGroup = ref(['上海'])
</script>

过滤器模式

通过 shape 属性设置为 "filter" 启用过滤器模式，适用于筛选场景：

vue 复制代码 
<template>
  <div>
    <!-- 单个复选框过滤器 -->
    <tiny-checkbox v-model="checked" shape="filter">筛选条件</tiny-checkbox>

    <!-- 复选框组过滤器 -->
    <tiny-checkbox-group v-model="checkedArr" shape="filter">
      <tiny-checkbox label="条件 1"></tiny-checkbox>
      <tiny-checkbox label="条件 2"></tiny-checkbox>
    </tiny-checkbox-group>
  </div>
</template>

<script setup>
import { ref } from 'vue'
import { TinyCheckbox, TinyCheckboxGroup } from '@opentiny/vue'

const checked = ref(true)
const checkedArr = ref(['条件 1'])
</script>

垂直布局

在 CheckboxGroup 上设置 vertical 为 true，复选框将垂直排列：

vue 复制代码 
<template>
  <tiny-checkbox-group v-model="checkboxGroup" vertical>
    <tiny-checkbox v-for="(city, index) in cities" :label="city" :key="index">
      {{ city }}
    </tiny-checkbox>
  </tiny-checkbox-group>
</template>

<script setup>
import { ref } from 'vue'
import { TinyCheckbox, TinyCheckboxGroup } from '@opentiny/vue'

const checkboxGroup = ref(['上海'])
const cities = ref(['上海', '北京', '广州', '深圳'])
</script>

自定义颜色

通过 CheckboxGroup 的 fill 属性自定义选中时的背景和边框颜色，text-color 自定义选中时的文本颜色：

vue 复制代码 
<template>
  <tiny-checkbox-group v-model="checked" fill="#fa9841" text-color="#fff">
    <tiny-checkbox-button label="复选框 1"></tiny-checkbox-button>
    <tiny-checkbox-button label="复选框 2"></tiny-checkbox-button>
  </tiny-checkbox-group>
</template>

<script setup>
import { ref } from 'vue'
import { TinyCheckboxButton, TinyCheckboxGroup } from '@opentiny/vue'

const checked = ref(['复选框 1'])
</script>

默认插槽

通过默认插槽自定义复选框的文本内容：

vue 复制代码 
<template>
  <tiny-checkbox-group v-model="checked">
    <tiny-checkbox label="复选框1">
      <template #default>
        <span style="color: #5e7ce0;">自定义样式文本</span>
      </template>
    </tiny-checkbox>
    <tiny-checkbox label="复选框2">
      <template #default>
        <span style="color: #fa9841;">警告色文本</span>
      </template>
    </tiny-checkbox>
  </tiny-checkbox-group>
</template>

<script setup>
import { ref } from 'vue'
import { TinyCheckbox, TinyCheckboxGroup } from '@opentiny/vue'

const checked = ref(['复选框 1'])
</script>

动态生成复选框组

复选框组数据可通过请求从后台获取，然后动态生成：

vue 复制代码 
<template>
  <tiny-checkbox-group v-model="checked" @change="valueChange">
    <tiny-checkbox-button v-for="item in list" :label="item.title" :key="item.id">
    </tiny-checkbox-button>
  </tiny-checkbox-group>
</template>

<script setup>
import { ref } from 'vue'
import { TinyCheckboxButton, TinyCheckboxGroup } from '@opentiny/vue'

const list = ref([])
const checked = ref([])

// 模拟异步请求
fetch('/api/cities').then(res => res.json()).then(data => {
  list.value = data
  checked.value = data.filter(item => item.checked).map(item => item.title)
})

function valueChange(val) {
  console.log('当前选择：', val)
}
</script>

事件

事件名 回调参数 说明
change (Checkbox) `(value: string number
change (CheckboxGroup) `(value: string[] number[])`
vue 复制代码 
<template>
  <tiny-checkbox-group v-model="checked" @change="valueChange">
    <tiny-checkbox-button label="复选框 1"></tiny-checkbox-button>
    <tiny-checkbox-button label="复选框 2"></tiny-checkbox-button>
  </tiny-checkbox-group>
</template>

<script setup>
import { ref } from 'vue'
import { TinyCheckboxButton, TinyCheckboxGroup } from '@opentiny/vue'

const checked = ref(['复选框 1'])

function valueChange(val) {
  console.log('选中值变化：', val)
}
</script>

只读态

通过 display-only 属性开启只显示模式，适用于详情页等非编辑场景：

vue 复制代码 
<template>
  <tiny-checkbox v-model="checked" display-only>只读复选框</tiny-checkbox>
</template>

<script setup>
import { ref } from 'vue'
import { TinyCheckbox } from '@opentiny/vue'

const checked = ref(true)
</script>

API 参考

Checkbox Props

属性名 类型 默认值 说明
checked boolean false 是否默认勾选
disabled boolean false 是否禁用
display-only string - 是否开启只显示模式
false-label `string number` -
indeterminate boolean false 半选状态（仅样式控制）
label `string number boolean`
modelValue / v-model `string number boolean`
name string - 原生 name 属性
shape 'filter' - 过滤器模式
text string - 复选框显示文本
true-label `string number` -

Checkbox Events

事件名 回调参数 说明
change `(value: string number

Checkbox Slots

插槽名 说明
default 自定义复选框内容

CheckboxGroup Props

属性名 类型 默认值 说明
disabled boolean false 是否禁用整组
fill string - 按钮激活时的填充色和边框色
max number - 可勾选的最大数量
min number - 可勾选的最小数量
modelValue / v-model `string[] number[]` -
options ICheckboxGroupOptions[] - 子项配置列表
shape 'filter' - 过滤器模式
size `'medium' 'small' 'mini'`
text-color string - 按钮激活时的文本颜色
type `'button' 'checkbox'` 'checkbox'
vertical boolean false 是否垂直排列

CheckboxGroup Events

事件名 回调参数 说明
change `(value: string[] number[])`

CheckboxGroup Slots

插槽名 说明
default 复选框组内容

CheckboxButton Props

属性名 类型 默认值 说明
checked boolean false 是否默认勾选
disabled boolean false 是否禁用
false-label `string number` -
label `string number boolean`
modelValue / v-model `string number boolean`
name string - 原生 name 属性
text string - 复选框文本
true-label `string number` -

CheckboxButton Slots

插槽名 说明
default 按钮内容

最佳实践

  1. 优先使用 CheckboxGroup ：多选场景始终使用 CheckboxGroup 包裹，通过 v-model 统一管理选中值数组，避免逐个管理 boolean 状态。

  2. 配置式优于插槽式 ：当选项数据来自接口或配置时，使用 options 属性配置式渲染，代码更简洁、更易维护。

  3. 全选逻辑用 computed ：全选/半选场景使用 computed 的 getter/setter 实现双向计算属性，逻辑清晰且自动同步。

  4. min/max 限制选择数 ：使用 min 和 max 属性限制可选数量，比手动校验更优雅，组件会自动禁用不可选的复选框。

  5. 按钮形式用于工具栏：CheckboxButton 适合工具栏、标签筛选等场景；普通 Checkbox 适合表单、设置项等场景。

  6. 过滤器模式用于筛选 ：搜索筛选场景使用 shape="filter" 过滤器模式，视觉上更贴合筛选交互。

  7. 垂直布局节省空间 ：选项较多或水平空间有限时，使用 vertical 垂直排列，避免水平溢出。

  8. 自定义颜色统一品牌 ：使用 fill 和 text-color 统一按钮式复选框的选中颜色，保持品牌一致性。

OpenTiny NEXT 是一套企业智能前端开发解决方案，以生成式 UI 和 WebMCP 两大核心技术为基础，对现有传统的 TinyVue 组件库、TinyEngine 低代码引擎等产品进行智能化升级，构建出面向 Agent 应用的前端 NEXT-SDKs、AI Extension、TinyRobot智能助手、GenUI等新产品，实现AI理解用户意图自主完成任务，加速企业应用的智能化改造。

相关推荐
秋天的一阵风1 小时前
✨ 代码秒跳转、自动补全？全靠 LSP 和 AST！
前端·后端·ai编程
程序员小淞1 小时前
写一个行政区划下拉选组件（异步+搜索）
前端
星栈1 小时前
用 Rust + Makepad 做一个 JSON 查看器：从零到能用的全过程
前端·rust
yijianace1 小时前
Python爬虫实战：分页爬取 + 详情页采集 + CSV存储
前端·爬虫·python
想吃火锅10052 小时前
【前端手撕】防抖节流
前端
MemoriKu2 小时前
Flutter 相册 APP 视频模态稳定化实战：从视频抽帧、Embedding 元数据到 Android 真机启动修复
android·开发语言·前端·flutter·架构·音视频·embedding
lichenyang4532 小时前
ArkUI 票根卡片：PathShape 真挖洞，shadow 沿凹陷外发光
前端
Cache技术分享2 小时前
432. Java 日期时间 API - 时间工具 TemporalQuery 详解
前端·后端
如果超人不会飞2 小时前
TinyVue Radio单选框组件使用指南
vue.js
热门推荐
01【AI】2026 年具身智能模型和世界模型总结02GitHub 镜像站点03Codex 下载安装指南：Windows 和 macOS 官方版下载042026 年 AI 编程工具终极横评：Cursor vs Claude Code vs Copilot vs Windsurf052026 AI 编程工具终极实战指南：Cursor vs Claude Code vs Copilot，开发者该怎么选？06AI科技热点日报 | 2026年6月1日07《置身钉内》原文-可播放阅读08【踩坑记录 | 第一篇】微软商店无法使用时，如何手动安装 OpenAI Codex？附`.msix`文件系统错误解决方法09CC-Switch 下载、安装与使用配置指南【2026.5.29】10Agnes AI 全模态 API 免费实测报告：文生图 + 文生视频完整测试