V Design

Components · 通用组件

Checkbox Interactions ​

四种复选框反馈共用同一套表单与无障碍契约，通过 effect 切换描边、波纹、Material 状态层或果冻形变。

Overview ​

AnimatedCheckbox 使用透明的原生 input[type='checkbox'] 承担表单、键盘和辅助技术语义，装饰元素只负责视觉表现。每种效果都补齐了键盘焦点、部分选中、禁用状态、44px 最小点击高度和减少动画支持。

Effect / 效果Feedback / 反馈Source / 来源
stroke（描边）方框轮廓让出缺口并绘制勾线Andrew Manzyk
ripple（波纹）选中波纹扩散，随后绘制勾线vishnupprajapat
material（Material）悬停、焦点和按压使用圆形状态层lenin55
jelly（果冻）选中时依次压缩、拉伸并回弹cssbuttons-io

Demo ​

Code ​

vue
<script setup lang="ts">
import { ref } from 'vue'
import { AnimatedCheckbox } from '@/library/web/components/checkbox-interactions'

const enabled = ref(false)
const partiallySelected = ref(true)
</script>

<template>
  <AnimatedCheckbox
    v-model="enabled"
    v-model:indeterminate="partiallySelected"
    effect="ripple"
    name="notifications"
    value="product-updates"
    label="接收产品更新"
  />
</template>

API ​

AnimatedCheckbox ​

Prop / 字段Type / 类型Default / 默认值Description / 中文含义
effect（动效类型）stroke | ripple | material | jellystroke选择复选框的视觉反馈方式
modelValue（选中值）booleanfalse当前是否选中，通过 v-model 双向绑定
label（标签）stringrequired可见标签；未提供插槽时也作为控件名称
indeterminate（部分选中）booleanfalse显示混合状态，可通过 v-model:indeterminate 控制
disabled（禁用）booleanfalse禁止操作并显示禁用状态
id（元素标识）stringauto原生输入框 ID；默认自动生成
name（表单字段名）string—原生表单提交使用的字段名
value（表单字段值）string | number—选中后提交的原生表单值
required（必选）booleanfalse启用原生表单必选校验
Event / 事件Payload / 参数Description / 中文含义
update:modelValue（更新选中值）boolean选中状态发生变化时触发
update:indeterminate（更新部分选中）boolean用户操作混合状态时触发 false
change（状态变化）boolean, Event返回新状态和原生事件

根元素上的其他 attributes 会透传给外层 label。标签内容可通过默认插槽替换。

Project Design 可以覆盖：

scss
--vd-checkbox-color
--vd-checkbox-accent
--vd-checkbox-focus
--vd-checkbox-duration
--vd-checkbox-size
--vd-checkbox-stroke-width

其中 --vd-checkbox-size（复选框尺寸）默认是 20px，--vd-checkbox-stroke-width（线条粗细）默认是 2px。

Behavior ​

  • 点击标签、触摸或在键盘焦点下按空格键都可以切换状态。
  • modelValue 是受控状态，组件通过事件通知父级更新，不在内部保存业务数据。
  • 用户操作部分选中状态时，同时清除 indeterminate 并更新选中值。
  • 禁用状态保留原生 disabled 行为，并移除可交互指针。
  • 系统启用减少动画时，描边、波纹和形变效果立即完成，状态仍然可辨认。

Notes ​

  • 动画只增强状态反馈，原生 checkbox 语义和可见标签仍然是必要信息。
  • 大批量筛选和密集表格应优先使用 material 或减少动效持续时间。
  • 四种效果均为 Uiverse HTML + CSS 样例的独立 Vue 3 适配。
  • 原样例均标注 MIT 许可证，来源和版权说明记录在项目的 THIRD_PARTY_NOTICES.md。