组件/Checkbox 复选框

Checkbox 复选框

在选中与未选中之间切换的复选控件

Verified自 0.3.4

用法

基础

点击方框或文案切换。

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 参考

属性

属性名类型默认值说明
modelValuebooleanfalse选中状态,配合 v-model 使用。
disabledbooleanfalse禁止切换,并移出 Tab 序列。
loadingbooleanfalse显示旋转环并禁止切换,不套用禁用态配色。
labelstring-方框旁的文案。
labelPlacement'start' | 'end''end'文案在方框前或后。
variant'checkmark' | 'fill''checkmark'checkmark 显示勾选标记,fill 只填充方框。
ariaLabelstring-没有可见文案时的可访问名称。
indeterminatebooleanfalse部分选中:显示横杠,点击后变为选中。

事件

事件名参数说明
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