dotsharp

Checkbox 复选框 ​

v-model 绑定布尔值，原生 <input type="checkbox"> 保留在 DOM 中，只负责状态、键盘与表单语义， 视觉部分由组件绘制。

基础用法 ​

vue
<script setup lang="ts">
import { ref } from "vue";
import { Checkbox } from "@sharpdotnut/dotsharp";

const accepted = ref(true);
const subscribed = ref(false);
</script>

<template>
  <Checkbox v-model="accepted" label="我接受服务条款" />
  <Checkbox v-model="subscribed" label="订阅更新" />
</template>

label 是纯文本；需要更自由的内容（链接、徽标）时改用默认插槽，插槽优先于 label。

不确定状态 ​

indeterminate 显示横线，用于“部分选中”。它只影响显示：用户点击后原生 checkbox 会先变成未选中的 false 或选中的 true，由你决定何时清除 indeterminate。

vue
<script setup lang="ts">
import { computed, reactive } from "vue";
import { Checkbox } from "@sharpdotnut/dotsharp";

const channels = reactive([
  { label: "邮件", checked: true },
  { label: "短信", checked: false },
  { label: "推送", checked: false },
]);

const all = computed({
  get: () => channels.every((channel) => channel.checked),
  set: (value: boolean) => channels.forEach((channel) => (channel.checked = value)),
});

const mixed = computed(
  () =>
    channels.some((channel) => channel.checked) && !channels.every((channel) => channel.checked),
);
</script>

<template>
  <Checkbox v-model="all" :indeterminate="mixed" label="全部通知" />
  <Checkbox
    v-for="channel in channels"
    :key="channel.label"
    v-model="channel.checked"
    :label="channel.label"
  />
</template>

禁用 ​

vue
<Checkbox label="已禁用" disabled />
<Checkbox label="已禁用且选中" :model-value="true" disabled />

表单校验 ​

validator 接收当前值，返回 false 表示通过；返回 true 或错误文案表示不通过。默认在切换与失焦时各校验一次，用 validateOn 调整；也暴露 validate() / clearValidate()。完整约定见表单指南。

API ​

属性类型默认值说明
v-modelbooleanfalse是否选中
labelstring—右侧文本；存在默认插槽时被插槽覆盖
indeterminatebooleanfalse不确定状态，显示横线
disabledbooleanfalse禁用：不可点击、不可聚焦
validator(value) => boolean | string—验证函数：false 通过，true / 字符串不通过
validateOn"input" | "blur" | ("input" | "blur")[]["input", "blur"]自动校验时机；传 [] 关闭自动校验
  • 根元素是 div（纵向排列，错误文案在下方），内部是原生 label；class / style 落在根元素上，其余属性与事件透传给原生 <input>， 因此 name、value、aria-label、id 等可以直接使用。
  • 视觉盒子 18px，四周有 40px 的悬停状态层，点按目标因此比盒子更大。
  • 默认插槽用作文本内容，优先于 label。

可访问性 ​

原生 checkbox 自带键盘空格切换与表单语义；indeterminate 通过原生 input.indeterminate 设置， 读屏会读作“混合”。悬停 / 焦点状态层不改变点击区域与焦点顺序。