Skip to content

Checkbox 复选框 ​

在一组备选项中进行多选。

基础用法 ​

单独使用可以表示两种状态之间的切换,使用 v-model 绑定一个 Boolean 类型的变量。

基础用法

禁用状态 ​

使用 disabled 属性来控制复选框的禁用状态。

禁用状态

复选框组 ​

适用于多个勾选框绑定到同一个数组的情景。

复选框组

中间状态 ​

indeterminate 属性用以表示 checkbox 的不确定状态,一般用于实现全选的效果。

中间状态(全选)

带边框 ​

使用 border 属性可以渲染为带有边框的复选框。

带边框

不同尺寸 ​

使用 size 属性来设置复选框的尺寸。

不同尺寸

可选项目数量的限制 ​

使用 min 和 max 属性能够限制可以被勾选的项目的数量。

可选项目数量的限制

自定义选中值 ​

使用 true-value 和 false-value 属性可以自定义复选框选中时和未选中时的值。

自定义选中值

在 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 | booleantrue
false-value未选中时的值string | number | booleanfalse
disabled是否禁用booleanfalse
indeterminate设置中间状态,只负责样式控制booleanfalse
border是否显示边框booleanfalse
size复选框尺寸'large' | 'default' | 'small''default'
name原生 name 属性string—
checked当前是否选中boolean—
idinput idstring—
tabindexinput tabindexstring | 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是否禁用booleanfalse
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)

类型导出 ​

名称说明
YhCheckboxPropsYhCheckbox props 类型
YhCheckboxEmitsYhCheckbox emits 类型
YhCheckboxSlotsYhCheckbox slots 类型
YhCheckboxExposeYhCheckbox expose 类型
YhCheckboxGroupPropsYhCheckboxGroup props 类型
YhCheckboxGroupEmitsYhCheckboxGroup emits 类型
YhCheckboxGroupOption组选项类型
YhCheckboxValueType复选框值类型
YhCheckboxInstanceYhCheckbox 实例类型
YhCheckboxGroupInstanceYhCheckboxGroup 实例类型

Released under the MIT License.