复选框组 checkbox-group

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

示例

基础用法

值是字符串数组，各选各的，再点一次即取消；组内有几项就有几个 Tab 停靠点

配料

芝士

培根

玉米

当前：cheese

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

const toppings = ref<string[]>(["cheese"]);
const items = [
  { value: "cheese", label: "芝士" },
  { value: "bacon", label: "培根" },
  { value: "corn", label: "玉米" },
];
</script>

<template>
  <!-- 交出 collection 即可，组标题与每个条目的方框、文本由组件按数据铺开 -->
  <XhCheckboxGroupRoot v-model:value="toppings" :collection="items" label="配料" name="topping" />
  <span>当前：{{ toppings.join("、") || "（无）" }}</span>
</template>

全选与半选

trigger 是第三态复选框，只有把全部条目的值交给 itemValues 才分得清 all 与 some

配料

全选（some）

芝士

培根

玉米

松露（禁用）

当前：cheese

<script setup lang="ts">
import { ref } from "vue";
import {
  XhCheckboxGroupItem,
  XhCheckboxGroupIndicator,
  XhCheckboxGroupItemText,
  XhCheckboxGroupLabel,
  XhCheckboxGroupRoot,
  XhCheckboxGroupTrigger,
} from "@xihan-ui/vue";

const items = [
  { value: "cheese", label: "芝士" },
  { value: "bacon", label: "培根" },
  { value: "corn", label: "玉米" },
  { value: "truffle", label: "松露（禁用）", disabled: true },
];
const itemValues = items.map((t) => t.value);
const toppings = ref<string[]>(["cheese"]);
</script>

<template>
  <XhCheckboxGroupRoot
    v-slot="{ checkedState }"
    v-model:value="toppings"
    :item-values="itemValues"
  >
    <XhCheckboxGroupLabel>配料</XhCheckboxGroupLabel>
    <!-- 方框与勾号／横杠由皮肤画，这里只写文案 -->
    <XhCheckboxGroupTrigger>
      <span>全选（{{ checkedState }}）</span>
    </XhCheckboxGroupTrigger>
    <XhCheckboxGroupItem
      v-for="t in items"
      :key="t.value"
      :value="t.value"
      :disabled="t.disabled"
    >
      <XhCheckboxGroupIndicator />
      <XhCheckboxGroupItemText>{{ t.label }}</XhCheckboxGroupItemText>
    </XhCheckboxGroupItem>
  </XhCheckboxGroupRoot>
  <span>当前：{{ toppings.join("、") || "（无）" }}</span>
</template>

横向排布

orientation 只出 data-orientation 交给皮肤排版，role=group 不接受 aria-orientation

通知渠道

邮件

短信

推送

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

const channels = ref<string[]>(["email"]);
const items = [
  { value: "email", label: "邮件" },
  { value: "sms", label: "短信" },
  { value: "push", label: "推送" },
];
</script>

<template>
  <XhCheckboxGroupRoot
    v-model:value="channels"
    :collection="items"
    label="通知渠道"
    orientation="horizontal"
  />
</template>

禁用与只读

整组禁用连隐藏输入一起退出提交，只读则仍能聚焦与朗读、只是改不动

整组禁用

芝士

培根

整组只读

芝士

培根

单项禁用

芝士

松露

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

const items = [
  { value: "cheese", label: "芝士" },
  { value: "bacon", label: "培根" },
];

// 单项禁用写在数据里，条目部件上不必再声明一遍
const partly = [
  { value: "cheese", label: "芝士" },
  { value: "truffle", label: "松露", disabled: true },
];
</script>

<template>
  <XhCheckboxGroupRoot :default-value="['cheese']" :collection="items" label="整组禁用" disabled />

  <XhCheckboxGroupRoot :default-value="['cheese']" :collection="items" label="整组只读" read-only />

  <XhCheckboxGroupRoot :default-value="['cheese']" :collection="partly" label="单项禁用" />
</template>

栅格排布

组容器的行列只是缺省排布，行内把 display 改成 grid 就能摆成多列

开通城市

北京

上海

广州

深圳

成都

杭州

<script setup lang="ts">
import { ref } from "vue";
import {
  XhCheckboxGroupItem,
  XhCheckboxGroupIndicator,
  XhCheckboxGroupItemText,
  XhCheckboxGroupLabel,
  XhCheckboxGroupRoot,
} from "@xihan-ui/vue";

const picked = ref<string[]>(["beijing", "chengdu"]);
const cities = [
  { value: "beijing", label: "北京" },
  { value: "shanghai", label: "上海" },
  { value: "guangzhou", label: "广州" },
  { value: "shenzhen", label: "深圳" },
  { value: "chengdu", label: "成都" },
  { value: "hangzhou", label: "杭州" },
];
</script>

<template>
  <XhCheckboxGroupRoot
    v-model:value="picked"
    style="display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: 8px 16px"
  >
    <XhCheckboxGroupLabel style="grid-column: 1 / -1">开通城市</XhCheckboxGroupLabel>
    <XhCheckboxGroupItem v-for="c in cities" :key="c.value" :value="c.value">
      <XhCheckboxGroupIndicator />
      <XhCheckboxGroupItemText>{{ c.label }}</XhCheckboxGroupItemText>
    </XhCheckboxGroupItem>
  </XhCheckboxGroupRoot>
</template>

受控与拦截

传了 value 就由宿主说了算，value-change 只报意图；这里最多留两项

通知渠道（最多两项）

邮件

短信

推送

回调

已选：email

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

const picked = ref<string[]>(["email"]);
const rejected = ref(false);
const channels = [
  { value: "email", label: "邮件" },
  { value: "sms", label: "短信" },
  { value: "push", label: "推送" },
  { value: "webhook", label: "回调" },
];

// 超过两项就不写回，界面停在原值
function onValueChange(details: { value: string[] }) {
  rejected.value = details.value.length > 2;
  if (!rejected.value) picked.value = details.value;
}
</script>

<template>
  <XhCheckboxGroupRoot
    :value="picked"
    :collection="channels"
    label="通知渠道（最多两项）"
    orientation="horizontal"
    @value-change="onValueChange"
  />
  <p>已选：{{ picked.join("、") || "（无）" }}{{ rejected ? " · 上一次超额，未写回" : "" }}</p>
</template>

整组换档

方框边长、字号、间距与选中色都是组件令牌，写在组容器上整组一起生效

紧凑

芝士

培根

缺省

芝士

培根

宽松

芝士

培根

换选中色

芝士

培根

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

const items = [
  { value: "cheese", label: "芝士" },
  { value: "bacon", label: "培根" },
];

// 一档尺寸就是一组令牌：方框边长、勾的字号、条目字号、条目内间距与条目间距
const compact =
  "--xh-checkbox-group-control-size: 13px; --xh-checkbox-group-control-font-size: 10px; --xh-checkbox-group-item-font-size: 13px; --xh-checkbox-group-item-gap: 6px; --xh-checkbox-group-gap: 8px";
const roomy =
  "--xh-checkbox-group-control-size: 20px; --xh-checkbox-group-control-font-size: 15px; --xh-checkbox-group-item-font-size: 17px; --xh-checkbox-group-item-gap: 10px; --xh-checkbox-group-gap: 14px";
// 选中态的底与描边各是一个令牌，两个一起换才不会只填色不换边
const green =
  "--xh-checkbox-group-control-bg-checked: #16a34a; --xh-checkbox-group-control-border-checked: #16a34a";
</script>

<template>
  <div style="display: flex; gap: 32px; flex-wrap: wrap; align-items: flex-start">
    <XhCheckboxGroupRoot :default-value="['cheese']" :collection="items" :style="compact" label="紧凑" />

    <XhCheckboxGroupRoot :default-value="['cheese']" :collection="items" label="缺省" />

    <XhCheckboxGroupRoot :default-value="['cheese']" :collection="items" :style="roomy" label="宽松" />

    <XhCheckboxGroupRoot :default-value="['cheese']" :collection="items" :style="green" label="换选中色" />
  </div>
</template>

数字主键

条目身份存在 DOM 属性上，值一律是字符串；数字主键在进出两侧各转一次

角色

管理员

审核员

访客

提交给后端：101

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

const roles = [
  { id: 101, name: "管理员" },
  { id: 102, name: "审核员" },
  { id: 103, name: "访客" },
];

// 条目数据交给组件前先把主键转成字符串
const options = roles.map((r) => ({ value: String(r.id), label: r.name }));

// 业务侧存数字，组件侧收字符串，转换收在一个可写 computed 里
const roleIds = ref<number[]>([101]);
const picked = computed({
  get: () => roleIds.value.map(String),
  set: (next) => (roleIds.value = next.map(Number)),
});
</script>

<template>
  <XhCheckboxGroupRoot
    v-model:value="picked"
    :collection="options"
    label="角色"
    orientation="horizontal"
    name="role"
  />
  <span>提交给后端：{{ roleIds.join("、") || "（无）" }}</span>
</template>

产物

层	值
自定义元素	<xh-checkbox-group>
Vue 组件	XhCheckboxGroupIndicator XhCheckboxGroupItem XhCheckboxGroupItemText XhCheckboxGroupLabel XhCheckboxGroupRoot XhCheckboxGroupTrigger
组合式函数	useCheckboxGroup
状态机	checkboxGroupMachine
皮肤	@xihan-ui/styles/checkbox-group.css

解剖

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

data-scope="checkbox-group"：root · label · item · indicator · item-text · hidden-input · trigger

Props

属性	类型	必填	说明
collection	CheckboxGroupNode[]		条目数据，显示文本与禁用的事实源。给了它，条目部件只需报 value。 缺省即回到「文本与禁用都写在条目部件上」的老路。
value	string[]		选中值集合。给定即受控：cell 直读 prop，写只发 onValueChange 不落内部值。
defaultValue	string[]
itemValues	string[]		组内全部条目的值，按书写顺序声明；不给时 checkedState 退化成 none / some 两态。
disabled	boolean		整组禁用：每一项都跟着禁用，且隐藏输入不参与提交。
readOnly	boolean		只读：仍可聚焦与朗读，但用户改不动。
invalid	boolean		校验失败标注，落到每个条目的 aria-invalid 上。
name	string		表单字段名；给定后每个条目的隐藏输入才带 name，同名多值一并提交。
orientation	Orientation		视觉排布，默认 vertical。只出 data-orientation，不出 aria-orientation。
onValueChange	(details: CheckboxGroupValueChangeDetails) => void		value 变化意图回调；受控时是唯一出口，非受控随内部写入一并通知。

状态机

状态：idle

事件：VALUE.SET · ITEM.TOGGLE · ALL.TOGGLE · FORM.RESET

判据：editable

connect API

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

成员	类型	说明
value	string[]
collection	readonly CheckboxGroupNodeMeta[]	collection 推出的条目元信息，按数据顺序排列；没给 collection 即空数组。
checkedState	CheckboxGroupCheckedState
disabled	boolean
readOnly	boolean
invalid	boolean
isChecked	(value: string) => boolean
setValue	(next: string[]) => void	整体替换选中集合。程序化入口，不受 readOnly 拦截。
toggleValue	(value: string) => void	翻转某个值；整组禁用或只读时无效。
getRootProps	() => T['element']
getLabelProps	() => T['element']
getItemProps	(props: CheckboxGroupItemProps) => T['element']
getIndicatorProps	(props: CheckboxGroupItemProps) => T['element']
getItemTextProps	(props: CheckboxGroupItemProps) => T['element']
getHiddenInputProps	(props: CheckboxGroupItemProps) => T['input']	条目的表单影子：一份视觉隐藏的原生 checkbox，由条目内部渲染。
getTriggerProps	() => T['element']	全选/半选的父复选框。必须写在 root 之内，它靠祖先链找到本组。

键盘

规格出处：W3C APG

按键	生效条件	行为
Tab / Shift+Tab	focus enters or leaves the group	组内有几个条目就有几个 Tab 停靠点（禁用条目也留一个），容器自己不占位；单选组的"整组一个停靠点"在这里不成立
Space	focus on item, group editable and item not disabled	翻转该条目的选中态；改不动时放行按键给页面滚动
Space	focus on trigger, group editable	可用条目未全选则一并勾上，已全选则一并取消；禁用条目不受影响