checkbox

使用时机

优先使用 <input type="checkbox">。原生元素内置焦点管理、Space 键激活、:checked 伪类、表单提交以及用于三态的 indeterminate JS 属性。role="checkbox" 仅适用于以下两种情形：

• 需要以 aria-checked="mixed" 暴露一个反映子项状态的”全选”三态复选框。
• 设计系统提供了无法替换的自定义复选框组件。

在非输入元素上实现 role="checkbox" 时，必须设置 aria-checked（该属性为必填），管理 tabindex="0"，并处理 Space 键的 keydown 事件。

键盘与焦点规范

根据 APG 复选框模式：

• Tab 键将焦点移至复选框。
• Space 键在 "true" 和 "false" 之间切换 aria-checked（三态时还包括 "mixed"）。
• Enter 键不激活复选框——仅 Space 键有效。（原生输入在大多数浏览器中同样忽略 Enter。）

激活后焦点保持在复选框上。

常见错误

• role="checkbox" 未设置 aria-checked 属性。该状态从元素出现在 DOM 中的那一刻起便为必填项。
• 将 aria-checked="true" 仅用作 class 钩子——只更新视觉样式而从不在点击时更新属性值。
• 自定义复选框响应点击事件但不响应 Space 键。
• 将原生 <input> 包裹在 <div role="checkbox"> 内——重复语义会使屏幕阅读器产生混淆。
• 三态控件通过 Space 键循环 false → true → mixed → false。APG 规定循环应为 false → true → false；mixed 由页面以编程方式设置，而非由用户触发。

示例

<!-- 推荐用法 -->
<label>
  <input type="checkbox" name="terms" required>
  I agree to the terms
</label>

<!-- 自定义三态"全选"控件 -->
<div
  role="checkbox"
  tabindex="0"
  aria-checked="mixed"
  aria-labelledby="selectAllLabel"
>
</div>
<span id="selectAllLabel">Select all rows</span>