Checkbox 复选框
在一组备选项中进行多选。
基础用法
单独使用可以表示两种状态之间的切换，使用 v-model 绑定一个 Boolean 类型的变量。
基础用法
禁用状态
使用 disabled 属性来控制复选框的禁用状态。
禁用状态
复选框组
适用于多个勾选框绑定到同一个数组的情景。
选中值: [ "选项A" ]
复选框组
中间状态
indeterminate 属性用以表示 checkbox 的不确定状态，一般用于实现全选的效果。
中间状态（全选）
带边框
使用 border 属性可以渲染为带有边框的复选框。
带边框
不同尺寸
使用 size 属性来设置复选框的尺寸。
不同尺寸
可选项目数量的限制
使用 min 和 max 属性能够限制可以被勾选的项目的数量。
最少选 1 项，最多选 2 项
可选项目数量的限制
自定义选中值
使用 true-value 和 false-value 属性可以自定义复选框选中时和未选中时的值。
当前绑定值类型: string, 值: no
自定义选中值
在 Nuxt 中使用
Checkbox 组件完全支持 Nuxt 3/4 的 SSR 渲染。在 Nuxt 项目中使用时，组件会自动导入。
Nuxt 中使用
SSR 注意事项：
- ✅ 单选及复选框组完全支持
- ✅ 所有视觉状态（选中、禁用、边框等）在 SSR 中一致
- ✅ 不确定状态（indeterminate）样式支持
SSR 安全性
Checkbox 组件已通过完整的 SSR 测试，确保服务端渲染结果与客户端激活后的结构一致，避免 Hydration 警告。
API
Checkbox Props
| 属性名 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| model-value / v-model | 绑定值 | string | number | boolean | — |
| value | 选中时的值（在 checkbox-group 中使用） | string | number | boolean | — |
| label | 显示的文本（如果没有 default slot） | string | — |
| true-value | 选中时的值 | string | number | boolean | true |
| false-value | 未选中时的值 | string | number | boolean | false |
| disabled | 是否禁用 | boolean | false |
| indeterminate | 设置中间状态，只负责样式控制 | boolean | false |
| border | 是否显示边框 | boolean | false |
| size | 复选框尺寸 | 'large' | 'default' | 'small' | 'default' |
| name | 原生 name 属性 | string | — |
| checked | 当前是否选中 | boolean | — |
| id | input id | string | — |
| tabindex | input tabindex | string | number | — |
Checkbox Events
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| change | 当绑定值变化时触发 | (value: string | number | boolean) => void |
Checkbox Slots
| 插槽名 | 说明 |
|---|---|
| default | 自定义默认内容 |
Checkbox Expose
| 属性名 | 说明 | 类型 |
|---|---|---|
| ref | 原生 input 元素 | Ref<HTMLInputElement> |
| checked | 是否选中 | boolean |
| focus | 使 input 获取焦点 | () => void |
| blur | 使 input 失去焦点 | () => void |
CheckboxGroup Props
| 属性名 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| model-value / v-model | 绑定值 | Array<string | number | boolean> | [] |
| size | 复选框组尺寸 | 'large' | 'default' | 'small' | — |
| disabled | 是否禁用 | boolean | false |
| min | 可被勾选的最小数量 | number | — |
| max | 可被勾选的最大数量 | number | — |
| text-color | 激活时的文字颜色 | string | — |
| fill | 激活时的填充色和边框色 | string | — |
| tag | 自定义元素标签 | string | Component | 'div' |
CheckboxGroup Events
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| change | 当绑定值变化时触发 | (value: Array<string | number | boolean>) => void |
CheckboxGroup Slots
| 插槽名 | 说明 |
|---|---|
| default | 自定义默认内容 |
主题变量
Checkbox 组件使用以下 CSS 变量，你可以通过覆盖这些变量来自定义样式：
| 变量名 | 说明 | 默认值 |
|---|---|---|
--yh-checkbox-font-size | 字体大小 | var(--yh-font-size-base) |
--yh-checkbox-text-color | 文字颜色 | var(--yh-text-color-regular) |
--yh-checkbox-input-size | 复选框大小 | 14px |
--yh-checkbox-input-border-color | 边框颜色 | var(--yh-border-color) |
--yh-checkbox-input-bg-color | 背景颜色 | var(--yh-fill-color-blank) |
--yh-checkbox-checked-bg-color | 选中背景色 | var(--yh-color-primary) |
--yh-checkbox-checked-border-color | 选中边框色 | var(--yh-color-primary) |
--yh-checkbox-checked-icon-color | 选中图标色 | var(--yh-fill-color-blank) |
--yh-checkbox-disabled-bg-color | 禁用背景色 | var(--yh-fill-color-light) |
--yh-checkbox-disabled-text-color | 禁用文字色 | var(--yh-text-color-placeholder) |
类型导出
| 名称 | 说明 |
|---|---|
YhCheckboxProps | YhCheckbox props 类型 |
YhCheckboxEmits | YhCheckbox emits 类型 |
YhCheckboxSlots | YhCheckbox slots 类型 |
YhCheckboxExpose | YhCheckbox expose 类型 |
YhCheckboxGroupProps | YhCheckboxGroup props 类型 |
YhCheckboxGroupEmits | YhCheckboxGroup emits 类型 |
YhCheckboxGroupOption | 组选项类型 |
YhCheckboxValueType | 复选框值类型 |
YhCheckboxInstance | YhCheckbox 实例类型 |
YhCheckboxGroupInstance | YhCheckboxGroup 实例类型 |