Checkbox 复选框
在选中与未选中之间切换的复选控件
用法
基础
点击方框或文案切换。
Loading demo...
变体
默认 checkmark 显示勾选标记;variant="fill" 只填充方框。
Loading demo...
禁用
Loading demo...
文案在前
labelPlacement="start" 把文案放在方框前。
Loading demo...
无文案
没有 label 或插槽时,必须传 aria-label。
Loading demo...
加载中
等待服务端确认时设置 loading:方框变为旋转环,未选中为灰色,已选中与部分选中为主色,期间不可切换。
Loading demo...
自定义文案
默认插槽替代 label。
Loading demo...
最佳实践
- 优先用可见的
label或插槽;只有没有可见文案时才用ariaLabel。 - 「正在提交」用
loading,「不可用」用disabled;用disabled表示忙碌会让控件像是永久不可用。 - 需要服务端确认时设置
loading,成功后再写回modelValue;失败时只撤下loading。
API 参考
属性
| 属性名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
modelValue | boolean | false | 选中状态,配合 v-model 使用。 |
disabled | boolean | false | 禁止切换,并移出 Tab 序列。 |
loading | boolean | false | 显示旋转环并禁止切换,不套用禁用态配色。 |
label | string | - | 方框旁的文案。 |
labelPlacement | 'start' | 'end' | 'end' | 文案在方框前或后。 |
variant | 'checkmark' | 'fill' | 'checkmark' | checkmark 显示勾选标记,fill 只填充方框。 |
ariaLabel | string | - | 没有可见文案时的可访问名称。 |
indeterminate | boolean | false | 部分选中:显示横杠,点击后变为选中。 |
事件
| 事件名 | 参数 | 说明 |
|---|---|---|
update:modelValue | (value: boolean) => void | 用户切换后触发,参数为新值。 |
change | (value: boolean) => void | 与 update:modelValue 同时触发。 |
插槽
| 插槽名 | 说明 |
|---|---|
default | 自定义文案,优先于 label。 |
概述
- 根节点是原生
<button role="checkbox">;点击、Enter 或 Space 切换。 - 受控组件:切换只派发事件,父级回写
modelValue后外观才更新。 indeterminate时aria-checked="mixed";加载中已选中与部分选中外观相同,靠它区分。disabled与loading都设置原生disabled;loading另设aria-busy="true",有可见文案时不渲染aria-label。- 在
TxFormItem中,表单项的 label 经for命名复选框;复选框自带文案时改用aria-labelledby,同时引用两者。表单的disabled同样生效。 - 减少动态效果时,加载环停止旋转。
技术实现
index.ts同时导出TuffCheckbox与TxCheckbox。- 源码:
packages/tuffex/packages/components/src/checkbox/。
查看源码
packages/tuffex/packages/components/src/checkbox/index.ts