复选框 checkbox

数据录入组件。三层同源：无头内核给出解剖与状态机，Vue 组件与自定义元素只是它的两层外壳，行为完全一致。

示例

基础用法

不传 checked 即为非受控

<script setup lang="ts">
import { XhCheckbox } from "@xihan-ui/vue";
</script>

<template>
  <XhCheckbox />
  <XhCheckbox default-checked />
  <XhCheckbox disabled />
</template>

三态

checked 传 "indeterminate" 表示部分选中，它不是第三个稳定态：点一下就落到 true

当前：indeterminate

<script setup lang="ts">
import { ref } from "vue";
import { XhCheckbox } from "@xihan-ui/vue";

const checked = ref<boolean | "indeterminate">("indeterminate");
</script>

<template>
  <XhCheckbox v-model:checked="checked" />
  <span>当前：{{ checked }}</span>
</template>

语气

tone 决定选中态的底与描边用哪族颜色，所以这里都置为选中

brandneutralsuccesswarningdangerinfo

<script setup lang="ts">
import { XhCheckbox } from "@xihan-ui/vue";

const tones = ["brand", "neutral", "success", "warning", "danger", "info"] as const;
</script>

<template>
  <div style="display: flex; align-items: center; gap: 16px; flex-wrap: wrap">
    <span v-for="t in tones" :key="t" style="display: inline-flex; align-items: center; gap: 6px">
      <XhCheckbox :tone="t" default-checked />
      <span>{{ t }}</span>
    </span>
  </div>
</template>

尺寸

size 同时缩放方框与勾选标记，不写就是缺省档

小缺省大

<script setup lang="ts">
import { XhCheckbox } from "@xihan-ui/vue";
</script>

<template>
  <div style="display: flex; align-items: center; gap: 16px">
    <span style="display: inline-flex; align-items: center; gap: 6px">
      <XhCheckbox size="sm" default-checked />
      <span>小</span>
    </span>
    <span style="display: inline-flex; align-items: center; gap: 6px">
      <XhCheckbox default-checked />
      <span>缺省</span>
    </span>
    <span style="display: inline-flex; align-items: center; gap: 6px">
      <XhCheckbox size="lg" default-checked />
      <span>大</span>
    </span>
  </div>
</template>

事件

checked-change 带一份 { checked }，非受控时内部翻转也照发一次

最近：（还没动过）

<script setup lang="ts">
import { ref } from "vue";
import { XhCheckbox } from "@xihan-ui/vue";

const log = ref<string[]>([]);

// 只留最近五条
function onCheckedChange(details: { checked: boolean }) {
  log.value = [details.checked ? "勾上" : "取消", ...log.value].slice(0, 5);
}
</script>

<template>
  <XhCheckbox @checked-change="onCheckedChange" />
  <span>最近：{{ log.join(" ← ") || "（还没动过）" }}</span>
</template>

业务取值

checked 只认布尔，用一个可写 computed 在中间换一次，绑上去的就是业务值

启用（enabled）专业版（free）

<script setup lang="ts">
import { computed, ref } from "vue";
import { XhCheckbox } from "@xihan-ui/vue";

// 后端收的是两个状态码，界面上只有勾与不勾
const status = ref<"enabled" | "disabled">("enabled");
const enabled = computed({
  get: () => status.value === "enabled",
  set: (next) => (status.value = next ? "enabled" : "disabled"),
});

// 也可以不落中间变量，直接在事件里写回业务值
const plan = ref<"pro" | "free">("free");
</script>

<template>
  <div style="display: flex; align-items: center; gap: 24px; flex-wrap: wrap">
    <span style="display: inline-flex; align-items: center; gap: 6px">
      <XhCheckbox v-model:checked="enabled" />
      <span>启用（{{ status }}）</span>
    </span>

    <span style="display: inline-flex; align-items: center; gap: 6px">
      <XhCheckbox
        :checked="plan === 'pro'"
        @update:checked="plan = $event ? 'pro' : 'free'"
      />
      <span>专业版（{{ plan }}）</span>
    </span>
  </div>
</template>

自渲外壳与命令式聚焦

组合式函数只给属性，节点由作者自己写，DOM 引用因此拿得到

当前：未勾选

<script setup lang="ts">
import { ref } from "vue";
import { useCheckbox } from "@xihan-ui/vue";

const { api } = useCheckbox({});
const box = ref<HTMLButtonElement | null>(null);
</script>

<template>
  <div style="display: flex; align-items: center; gap: 12px">
    <!-- 两个节点与组件外壳渲染的是同一套：属性来自 getRootProps 与 getIndicatorProps -->
    <button ref="box" v-bind="api.getRootProps()">
      <span v-bind="api.getIndicatorProps()" />
    </button>
    <button type="button" @click="box?.focus()">聚焦</button>
    <button type="button" @click="box?.blur()">失焦</button>
    <button type="button" @click="api.setChecked(!api.checked)">翻转</button>
    <span>当前：{{ api.checked ? "已勾选" : "未勾选" }}</span>
  </div>
</template>

随表单提交

给了 name 才生出表单影子：勾上才提交，半选按未勾处理，与原生复选框一致

已阅读条款（勾上才提交） 订阅周报（没勾就整条不进 FormData） 半选（按未勾处理，不提交） 不参与提交

<script setup lang="ts">
import { XhButton, XhCheckbox } from "@xihan-ui/vue";
import { ref } from "vue";

const submitted = ref("");

function onSubmit(event: Event) {
  const data = new FormData(event.target as HTMLFormElement);
  const keys = [...data.entries()].map(([k, v]) => `${k}=${v}`);
  submitted.value = keys.length ? keys.join("  ") : "（一个字段都没提交）";
}
</script>

<template>
  <form style="display: grid; gap: 12px" @submit.prevent="onSubmit">
    <label><XhCheckbox name="agree" default-checked /> 已阅读条款（勾上才提交）</label>
    <label><XhCheckbox name="news" /> 订阅周报（没勾就整条不进 FormData）</label>
    <label><XhCheckbox name="partial" default-checked="indeterminate" /> 半选（按未勾处理，不提交）</label>
    <!-- 不给 name 就没有影子节点，既有 DOM 一个字节不变 -->
    <label><XhCheckbox /> 不参与提交</label>

    <div>
      <XhButton type="submit" size="sm">提交</XhButton>
    </div>

    <span v-if="submitted">表单收到：{{ submitted }}</span>
  </form>
</template>

产物

层	值
自定义元素	<xh-checkbox>
Vue 组件	XhCheckbox
组合式函数	useCheckbox
状态机	checkboxMachine
皮肤	@xihan-ui/styles/checkbox.css

解剖

部件名即 data-part 属性值，也是皮肤的选择器。加粗的是必备部件，不渲染它组件不工作（Web Components 适配器会在诊断通道上报 wc.missing-part）。

data-scope="checkbox"：root · indicator · hidden-input

Props

属性	类型	必填	说明
checked	CheckboxCheckedState
defaultChecked	CheckboxCheckedState
disabled	boolean
name	string		表单字段名；给了 hidden-input 才带 name 并参与提交。
value	string		提交出去的值，缺省 'on'，与原生复选框一致。
tone	Tone		语气：brand / neutral / success / warning / danger / info，决定选中态用哪族颜色。
size	Size		尺寸：sm / md / lg，决定方框边长与勾的字号档位。
onCheckedChange	(details: CheckboxCheckedChangeDetails) => void		checked 变化意图回调；受控时是唯一出口，非受控随内部转移一并通知。

状态机

状态：off · on · indeterminate

事件：TOGGLE · CHECK · UNCHECK · CONTROLLED.ON · CONTROLLED.OFF · CONTROLLED.INDETERMINATE · FORM.RESET

判据：isCheckedControlled · defaultsToChecked · defaultsToIndeterminate

connect API

useCheckbox 产出的对象。getXxxProps() 铺到对应部件的宿主元素上，其余是可读状态与操作入口。

成员	类型	说明
checked	CheckboxCheckedState
setChecked	(next: boolean) => void	半选只能由 checked prop 给出，这里只接受全选 / 全不选。
getRootProps	() => T['button']
getIndicatorProps	() => T['element']
getHiddenInputProps	() => T['input']	表单影子：勾上才提交，半选按未勾处理。给了 name 才带 name。

键盘

规格出处：W3C APG

按键	生效条件	行为
Space / Enter	focus in root, not disabled	切换 checked 状态