0 Fork 0

Files

T

2026-10-09 17:32:14 +08:00

3.4 KiB

Raw Blame History

title, description

title	description
Checkbox 复选框	支持选中、未选中与半选三种状态的独立勾选控件

Checkbox 复选框

Checkbox 用于在一组互不排斥的选项里多选，或表示单个布尔开关（如「同意协议」）。

何时使用

多选：一组选项可以用任意组合选中；
单个布尔：如「记住我」「同意条款」；
父子联动：父项用 indeterminate 表达「部分选中」（见下方示例）；
只有一个开关、立即生效的场景请用 Switch。

基础用法

v-model 绑定 boolean。

半选联动

indeterminate 是纯展示状态：组件不会自动推导它，需要业务根据子项结果计算。

状态	表现
`modelValue = true`	显示勾选（优先级最高，会强制清掉半选）
`modelValue = false` + `indeterminate = true`	显示减号（半选）
两者都为 `false`	显示空框

禁用态

富内容

默认插槽可以放任意内容（多行说明、链接、标签），此时仍然整块可点击。

API

Props

名称	类型	默认值	说明
`modelValue`	`boolean`	`false`	双向绑定的选中状态
`indeterminate`	`boolean`	`false`	半选状态（仅展示，需业务自行计算）。选中时会被忽略
`disabled`	`boolean`	`false`	禁用态
`name`	`string`	—	原生 `name`，用于表单提交分组
`value`	`string \| number \| boolean`	—	原生 `value`，随表单提交的值

Events

名称	参数	说明
`update:modelValue`	`(value: boolean)`	勾选状态变化
`change`	`(value: boolean, event: Event)`	同上，附带原生事件
`focus`	`(event: FocusEvent)`	获得焦点
`blur`	`(event: FocusEvent)`	失去焦点

Slots

名称	参数	说明
`default`	—	复选框文案（可放富内容）。为空时不渲染文字容器

类型定义

export interface CheckboxProps {
  modelValue?: boolean
  indeterminate?: boolean
  disabled?: boolean
  name?: string
  value?: string | number | boolean
}

样式变量

变量	默认值	说明
`--g3-checkbox-size`	`16px`	勾选框边长
`--g3-radius-sm`	`4px`	勾选框圆角
`--g3-color-primary`	`#18181b`	选中态底色与边框
`--g3-bg-disabled` / `--g3-text-disabled`	`rgba(0,0,0,.04 / .25)`	禁用态

实现说明

底层是原生 <input type="checkbox">，通过 <label> 包裹：因此键盘 Space 切换、点击文字、屏幕阅读器状态全部由浏览器负责，组件只负责视觉；
indeterminate 是 DOM property（不是 attribute），Vue 的绑定语法覆盖不到，组件内部在 mounted 与相关 prop 变化时手动写入 input.indeterminate；
勾选态优先：modelValue = true 时会强制把 DOM 的 indeterminate 置为 false，避免「已勾选却显示减号」；
原生 input 视觉上隐藏（opacity: 0 + 1px 尺寸），但保留在布局中，这样 :focus-visible 的焦点环可以作用在自绘的方框上，键盘用户依然有焦点提示。

3.4 KiB Raw Blame History Unescape Escape