Checkbox 使用手册

许可阅读：首次阅读组件文档、源码或 npm 使用流程，先读完整 LICENSE；同任务同版本去重。公开 API 配置与内部实现修改分别按许可处理；全部组件使用统一运行包，源码权益以许可为准。

组件介绍

选择一个或多个独立选项，支持选中、未选中和部分选中状态，适合表单与批量选择。

使用选择

用于独立开关或多项选择。互斥单选用 Radio，立即生效的二态设置用 Switch；DataTable 选择列优先使用其内置选择协议。

• 独立布尔状态使用 bind:checked；多选数组使用 bind:group 并为各项提供稳定 value。

• indeterminate 表示部分选中；与 checked 分开管理。提供标签或 ariaLabel，禁用使用 disabled。

快速开始

以下示例展示推荐的基本组合。更多场景与组合限制见后文。

<script lang="ts">	import { Checkbox } from '@snowui-design-system/components';	let subscribed = $state(false);</script> <Checkbox bind:checked={subscribed}>Email me product updates</Checkbox>

API

未重新声明的继承能力请查所属基础组件文档；本表只列本组件源码具名公开属性。

使用边界与详细说明

布局模型

主布局模型：内联外壳布局。定义见 ../../../specs/maintainers/LayoutProtocol.md §12.4（源码参考：specs/maintainers/LayoutProtocol.md）。

Checkbox 属于“控件视觉体 + label”的内联外壳子类：

• 根节点保持 inline-flex，内容整体 Hug。

• .snowui-checkbox-visual 是固定 Hug 的控件视觉体。

• .snowui-checkbox-label 是可选标签，空间充足时 Hug，受限时允许收缩并单行省略；原始内容及完整原生名称保留。

• visual 与 label 的距离由 --snowui-checkbox-gap 管理，可通过 gap 或 --snowui-checkbox-gap-override 设置首选值；有效间距至少 4 CSS px。

• size 表示包含透明留白的控件占位尺寸，不改变 label 的布局策略。

• 四周留白为 size / 16，可见图形宽高为 size × 0.875；例如 size={32} 占位 32×32px、图形 28×28px、四边各 2px。留白与图形随 size、根字号和尺寸 Token 等比缩放，留白仍可点击。

• 留白由共享控件壳持有，label 位于壳外；内边框继续按名义 size 的 0.0625 计算，圆角、Dot 与选中环按可见图形尺寸计算。

使用示例

<script>  import { Checkbox } from '@snowui-design-system/components';  let checked = $state(false);  let indeterminate = $state(false);</script>   <Checkbox bind:checked>复选框</Checkbox>  <Checkbox bind:indeterminate>不确定状态</Checkbox>  <Checkbox bind:checked size={24}>大号复选框 (24px)</Checkbox>  <Checkbox checked disabled>禁用复选框</Checkbox>

Unchecked（未选中）

• 空的方框

• 灰色边框

Checked（选中）

• 显示勾选图标

• 主题色背景和边框

Indeterminate（不确定）

• 显示横线图标

• 主题色背景和边框

• 常用于"全选"场景

图标

• 勾选图标: 选中状态显示

• 横线图标: 不确定状态显示

• 使用 28×28 SVG 描边路径绘制，随组件尺寸缩放并继承选中态颜色

无障碍性

• 使用原生 <input type="checkbox"> 确保键盘导航

• 支持 Tab 键聚焦

• 支持 Space 键切换

• 支持 indeterminate 属性

• 禁用状态下 tabindex=-1

单个复选框

<script lang="ts">  import { Checkbox } from '@snowui-design-system/components';  let checked = $state(false);</script> <Checkbox bind:checked>同意条款</Checkbox>

全选/部分选中

<script>  import { Checkbox, Frame } from '@snowui-design-system/components';   let items = $state([    { id: 1, checked: false },    { id: 2, checked: false },    { id: 3, checked: false }  ]);   let allChecked = $derived(items.every(item => item.checked));  let someChecked = $derived(items.some(item => item.checked) && !allChecked);</script>  <Frame class="flex flex-col gap-2 p-4">  <Checkbox    checked={allChecked}    indeterminate={someChecked}    onclick={() => {      const newState = !allChecked;      items.forEach(item => item.checked = newState);    }}  >    全选  </Checkbox>   <Frame class="flex flex-col gap-2 pl-6 border-l border-black-10">    {#each items as item}      <Checkbox bind:checked={item.checked}>选项 {item.id}</Checkbox>    {/each}  </Frame></Frame>

样式规则 (Style Spec)

2. 默认样式 (Defaults)

• Display: inline-flex, align-items: center

• Gap: 首选 var(--gap-1)，缩放和零值下的有效间距仍至少为 4 CSS px。

• Cursor: pointer (Disabled 时为 default)

• Font: var(--text-14) (14px), line-height: var(--leading-14) (20px)

3. CSS 变量 (Variables)

组件使用 CSS 变量实现等比缩放：

--snowui-checkbox-size: var(--size-4); /* 基准 16px */--snowui-checkbox-size-resolved: var(--snowui-checkbox-size-override, var(--snowui-checkbox-size));--snowui-checkbox-radius: calc(var(--snowui-checkbox-visual-size) * 0.3125); /* 可见尺寸的 31.25% */--snowui-checkbox-radius-resolved: var(--snowui-checkbox-radius-override, var(--snowui-checkbox-radius));--snowui-checkbox-border-width: calc(var(--snowui-checkbox-size-resolved) * 0.0625); /* 16px 时 1px，32px 时 2px */--snowui-checkbox-border-width-resolved: var(--snowui-checkbox-border-width-override, var(--snowui-checkbox-border-width));--primary: var(--primary, var(--black-100, #000000)); /* 使用全局 Primary Token (默认黑色) */

Unchecked

• Visual: 透明背景 + var(--black-20) 边框

• Icon: 勾选与横线均不可见

• Hover: 填充保持不变；独立 inset 覆盖层在基础 20% 黑色边框上再叠加 20% 黑色，默认等效约 36% 黑色；仅此状态适用 StyleSpec §2.4.3 例外

Checked / Indeterminate

• 触发: 原生 input 的 :checked / :indeterminate 通过 sibling 选择器驱动

• Visual: var(--primary) 背景 + 边框

• Icon: color: var(--static-white-100)；checked 使用路径绘制，indeterminate 保留缩放 / 透明度过渡

• Hover: 填充与 inset 边框统一在主色上混合 20% Static White

Disabled

• Attr: [data-disabled="true"]

• Style: opacity: 0.5, pointer-events: none, cursor: default

5. 交互细节

• 点击区域: 原生 <input> 使用 position: absolute; inset: 0 覆盖整个 label 区域，确保点击响应灵敏。

• Focus: 支持键盘导航，聚焦时显示 20% primary 的 Ring。

• 动画:

  • 容器: hover 填充与 inset 边框使用相同颜色和时序

  • checked 勾选: 参考 Fluid Functionalism 的 pathLength 语义，进入使用 200ms ease-out 绘制；取消选择时以常规 150ms ease-out 随底色淡出，不反向绘制

  • indeterminate 横线: 与 Radio 状态动效一致，使用 150ms ease-out

  • prefers-reduced-motion: reduce: 取消视觉体、勾选与横线过渡，直接显示最终状态