Checkbox 复选框

复选框（Checkbox）用于让用户在两种状态之间切换，支持单选、多选组合、开关模式等场景。

基础用法

通过 v-model 实现双向绑定。

<TCheckbox label="默认复选框"/>
<TCheckbox v-model="agreed" label="已勾选"/>
<TCheckbox label="禁用" disabled/>
<TCheckbox label="禁用（已勾选）" disabled model-value="true"/>

内联排列

通过 inline 属性让复选框水平排列。

TCheckboxGroup 组模式（推荐）

通过 TCheckboxGroup 包裹多个 TCheckbox，v-model 自动管理选中值数组，name / inline / disabled / validation 可统一设置并下发给子项。

<TCheckboxGroup v-model="checkedArr">
  <TCheckbox value="apple" label="苹果" />
  <TCheckbox value="banana" label="香蕉" />
  <TCheckbox value="orange" label="橙子" />
</TCheckboxGroup>

options 模式（数组生成）

通过 options 属性传入字符串数组或对象数组，自动生成 TCheckbox，无需手动写子组件。

字符串数组：每个字符串同时作 label 和 value。
对象数组：可指定 label、value、disabled。
自定义渲染：通过 #option 插槽自定义每个选项的标签内容。

查看代码

<!-- 字符串数组 -->
<TCheckboxGroup v-model="checkedArr" :options="['Apple', 'Pear', 'Orange']" />

<!-- 对象数组 -->
<TCheckboxGroup v-model="checkedArr" :options="[
  { label: '苹果', value: 'apple' },
  { label: '香蕉', value: 'banana' },
  { label: '橙子', value: 'orange' },
]" />

<!-- 带禁用项 -->
<TCheckboxGroup v-model="checkedArr" disabled :options="[
  { label: '苹果', value: 'apple' },
  { label: '香蕉', value: 'banana', disabled: true },
]" />

半选状态 (Indeterminate)

通过 indeterminate 属性设置半选状态。典型场景：树形或全选/反选列表中，当子项部分被勾选时，父级复选框显示为半选状态，表示"不完全全选"。

注意：半选状态是纯视觉的，不影响 v-model 的值。搭配 toggleIndeterminate 即可恢复为正常勾选/取消状态。

<TCheckbox indeterminate label="半选状态"/>

验证状态

通过 validation 属性设置验证状态，配合 .valid-feedback / .invalid-feedback 显示提示。

<TCheckbox label="有效状态" validation="valid"/>
<div class="valid-feedback">选择正确！</div>

<TCheckbox label="无效状态" validation="invalid"/>
<div class="invalid-feedback">请勾选此选项。</div>

自定义标签（插槽）

通过 default 插槽自定义标签内容，支持富文本和图标。

<TCheckbox>
  <span>我已阅读并同意<span class="text-danger">《用户协议》</span></span>
</TCheckbox>

API

TCheckbox 属性 (Props)

属性名	说明	类型	默认值
v-model	绑定值（独立模式: boolean，组模式: 自动接管）	boolean	false
value	组模式下标识选项的值	any	undefined
label	标签文本	string	undefined
inline	内联排列	boolean	false
disabled	禁用状态	boolean	false
indeterminate	半选状态（仅视觉）	boolean	false
validation	验证状态	'valid' | 'invalid'	undefined
id	原生 id	string	undefined
name	原生 name	string	undefined
required	必填	boolean	false

TCheckbox 事件 (Emits)

事件名	说明	回调参数
update:modelValue	值变化时触发（独立模式）	(value: boolean) => void

TCheckboxGroup 属性 (Props)

属性名	说明	类型	默认值
v-model	选中的值数组	any[]	[]
options	选项数组（字符串或对象），设置后自动生成 TCheckbox	(string | { label: string, value?: any, disabled?: boolean })[]	undefined
name	分组名（自动传递给子 TCheckbox）	string	undefined
inline	内联排列（自动传递给子复选框）	boolean	false
disabled	全部禁用	boolean	false
validation	验证状态（自动传递给子复选框）	'valid' | 'invalid'	undefined

TCheckboxGroup 事件 (Emits)

事件名	说明	回调参数
update:modelValue	选中值数组变化时触发	(value: any[]) => void
change	选中值数组变化时触发	(value: any[]) => void

TCheckbox 插槽 (Slots)

插槽名	说明
default	自定义标签内容（替代 label 属性）

TCheckboxGroup 插槽 (Slots)

插槽名	说明	作用域参数
default	自定义子项（当未设置 options 时）	—
option	自定义选项标签（当设置了 options 时）	{ option: { label, value, disabled }, checked: boolean }