Checkbox

自定义复选框,默认使用 i-tripo:check 图标作为勾选指示符。组件默认采用白色描边 + 品牌紫色填充,适合暗色背景;在亮色页面中演示时请用深色容器衬托。

基本用法

受控 v-model

当前状态: 未勾选

<script setup lang="ts">
import { Checkbox } from '@tripo3d/design';
import { ref } from 'vue';

const agreed = ref(false);
</script>

<template>
  <Checkbox v-model="agreed" />
</template>

禁用

disabled

<Checkbox disabled />
<Checkbox :model-value="true" disabled />

自定义指示符

自定义内部图标

通过默认插槽替换勾选时的指示符,可用于表达 indeterminate 等状态。

<!-- 以一条横线表示"部分选中" -->
<Checkbox :model-value="true">
  <span class="block w-3 h-0.5 bg-white rounded-full" />
</Checkbox>

<!-- 或直接传入任意文本 / 图标节点 -->
<Checkbox :model-value="true">
  <span class="text-white text-xs font-bold">✓</span>
</Checkbox>

API

Props

名称	类型	默认值	说明
modelValue	boolean	—	受控勾选状态
defaultValue	boolean	—	非受控默认值
disabled	boolean	—	禁用
required	boolean	—	必填(表单内使用)
name	string	—	表单字段名
value	string	—	提交值,默认 on
class	string	—	额外 class

其余 props 透传至 reka-ui CheckboxRoot,详见 reka-ui 文档。

Events

事件	Payload	说明
update:modelValue	(value: boolean)	勾选状态变化

Slots

插槽	作用域	说明
default	—	自定义勾选指示符,默认内置 i-tripo:check。仅在勾选态(data-state=checked)时渲染

可访问性

• 基于 reka-ui CheckboxRoot,具备正确的 role="checkbox" 与 aria-checked 语义
• 支持键盘 Space 切换勾选状态
• 表单场景中请搭配 <Label :for="id"> 提升可访问性