For AI agents: the complete documentation index is available at https://a3s-lab.github.io/UI/v0.4.0/llms.txt, the full documentation bundle is available at https://a3s-lab.github.io/UI/v0.4.0/llms-full.txt, and this page is available as Markdown at https://a3s-lab.github.io/UI/v0.4.0/components/checkbox.md.

复选框

复选框让用户从一组非互斥选项中选择零项、一项或多项。它适合随表单一起提交的选择；会立即改变系统状态的二元设置应使用开关。

接收发布状态

选择团队需要接收通知的渠道。

电子邮件

在发布完成或失败时发送摘要。

桌面通知

仅在此设备在线时提醒。

短信

当前工作区尚未配置短信服务。

安装Terminal

npm install @a3s-lab/ui@0.4.0

<div class="field" data-orientation="horizontal">
  <input class="input" type="checkbox" id="include-logs" name="include-logs" />
  <label for="include-logs">附带诊断日志</label>
</div>

import "@a3s-lab/ui/a3s.css";
import "@a3s-lab/ui/all";

用法

导入 Tailwind 与完整 A3S 样式包：

@import "tailwindcss";
@import "@a3s-lab/ui/a3s.css";

为原生复选框添加 input 类，并使用 label 建立名称关联。只有一个输入时，标签可以直接与它配对。

<div class="field" data-orientation="horizontal">
  <input class="input" type="checkbox" id="include-logs" name="include-logs" />
  <label for="include-logs">附带诊断日志</label>
</div>

需要按组件加载时，依次导入基础样式、复选框结构、字段结构和 A3S 视觉样式。CDN 与其他接入方式见安装。

@import "@a3s-lab/ui/base.css";
@import "@a3s-lab/ui/components/checkbox.css";
@import "@a3s-lab/ui/components/field.css";
@import "@a3s-lab/ui/styles/a3s.css";

参数

参数	值	用途
根元素	`<input type="checkbox">`	保留浏览器的表单、键盘和无障碍语义
`class`	`input`	应用复选框结构与视觉样式
`checked`	布尔属性	表示已选择；服务端渲染时只用于真实默认值
`disabled`	布尔属性	阻止交互；所在 `.field` 同步设置 `data-disabled`
`aria-invalid`	`true`	在校验失败后表达无效状态
`aria-describedby`	元素 ID	关联帮助、限制或错误信息
`indeterminate`	DOM 属性	表示子项只选中一部分，不等同于第三个提交值

状态与变体

未选中和已选中是用户可操作的常态。禁用状态必须同时解释原因；无效状态只在用户提交或离开字段后出现，避免页面首次加载就显示错误。

包含源文件

包含构建缓存

确认已移除敏感数据

导出前必须完成确认。

包含审计归档

只有工作区所有者可以更改此项。

<div class="grid gap-4">
    <div class="field" data-orientation="horizontal">
      <input class="input" type="checkbox" id="state-selected" name="state-selected" defaultChecked />
      <label for="state-selected">包含源文件</label>
    </div>
    <div class="field" data-orientation="horizontal">
      <input class="input" type="checkbox" id="state-unselected" name="state-unselected" />
      <label for="state-unselected">包含构建缓存</label>
    </div>
    <div class="field" data-orientation="horizontal" data-invalid>
      <input class="input" type="checkbox" id="state-required" name="state-required" aria-invalid="true" aria-describedby="state-required-error" />
      <section>
        <label for="state-required">确认已移除敏感数据</label>
        <p id="state-required-error" role="alert">导出前必须完成确认。</p>
      </section>
    </div>
    <div class="field" data-orientation="horizontal" data-disabled>
      <input class="input" type="checkbox" id="state-disabled" name="state-disabled" disabled />
      <section>
        <label for="state-disabled">包含审计归档</label>
        <p>只有工作区所有者可以更改此项。</p>
      </section>
    </div>
  </div>

indeterminate 只能通过 DOM 属性设置，常用于“全选”控件。它仍会按 checked 属性决定表单提交结果，因此应用必须分别维护两个状态。

const selectAll = document.querySelector("#select-all");
const selectedCount = 2;
const totalCount = 5;

selectAll.checked = selectedCount === totalCount;
selectAll.indeterminate = selectedCount > 0 && selectedCount < totalCount;

多项选择

相关选项使用 fieldset 和 legend 分组。标签回答“这一项是什么”，说明文字补充后果或限制；不要把整段说明都塞进标签。

选择导出内容

至少选择一项，导出任务才可开始。

文档

评论与批注

版本历史

<fieldset class="fieldset">
    <legend data-variant="legend">选择导出内容</legend>
    <p>至少选择一项，导出任务才可开始。</p>
    <div class="grid gap-3">
      <div class="field" data-orientation="horizontal">
        <input class="input" type="checkbox" id="export-documents" name="export-content" value="documents" defaultChecked />
        <label for="export-documents">文档</label>
      </div>
      <div class="field" data-orientation="horizontal">
        <input class="input" type="checkbox" id="export-comments" name="export-content" value="comments" defaultChecked />
        <label for="export-comments">评论与批注</label>
      </div>
      <div class="field" data-orientation="horizontal">
        <input class="input" type="checkbox" id="export-history" name="export-content" value="history" />
        <label for="export-history">版本历史</label>
      </div>
    </div>
  </fieldset>

表格中的行选择属于表格或数据网格的整体交互。表头“全选”必须同步可见行、跨页选择范围和不确定状态，不能只在复选框文档中拼出一个没有行为的静态表格。

可访问性

每个复选框都必须有可访问名称，优先使用与 id 配对的可见 label。
相关多选项使用 fieldset 与 legend；不要为普通 .field 添加冗余的 role="group"。
空格键切换聚焦的原生复选框。不要用自定义点击处理替换浏览器行为，也不要阻止标签点击。
帮助或错误信息通过 aria-describedby 关联；校验失败时同步设置 aria-invalid="true"。
禁用项仍应显示标签和不可用原因。若用户仍需理解或复制内容，优先只禁用控件，不要隐藏整行。
indeterminate 只是部分选择的视觉和无障碍状态；提交值仍由 checked 决定。

#复选框

#用法

#参数

#状态与变体

#多项选择

#可访问性

复选框

用法

参数

状态与变体

多项选择

可访问性