Checkbox 复选框

待提交的勾选：放在表单里，和别的字段一起提交。立即生效的开关请用 Switch。

基础用法

待提交的勾选，放在表单里和别的字段一起提交。半选态只是视觉与 aria 状态，点击后一律变成选中。

<pt-checkbox>同意条款</pt-checkbox>
<pt-checkbox checked>已选中</pt-checkbox>
<pt-checkbox indeterminate>部分选中</pt-checkbox>
<pt-checkbox disabled>禁用</pt-checkbox>

什么时候用哪个

• Checkbox：待提交的勾选。放在表单里，和别的字段一起提交。
• Switch：立即生效的开关。改了就生效，没有「提交」这一步。

两者的受控值都是 checked + ptChange，键盘行为也一样，区别只在语义。 Switch 的页面在这里。

半选态

indeterminate 表示「部分子项被选中」。它只是视觉与 aria 状态（aria-checked="mixed"），不是第三个值： 点击后一律变成选中 —— 这是原生 input[type=checkbox] 的行为，读屏用户的预期也是这样。

键盘操作

按键	行为
Space	切换选中
Enter	不切换 —— 与原生 checkbox 一致，Enter 留给表单提交

无障碍

方框是 role="checkbox"，可访问名来自插槽里的标签文案。插槽里没有文案时（例如表格的全选列） 必须给 aria-label —— 在 React / Vue / Angular 包装层里属性名是 ariaLabelText。

标签文案里放了链接或按钮时，点它们是在用它们，不是在切换 —— 与原生 <label> 处理交互式子元素的方式一致。

对宿主调用 click() 同样会切换并发 ptChange（与原生 checkbox.click() 一致）， 所以文字需要和方框分开摆放时，可以用 Label 的 for 指向它。Switch 也一样。

表单里的值

未选中时提交 null 而不是空字符串：原生 checkbox 未勾选时整个字段不出现在 FormData 里， 服务端据此区分「没勾」和「勾了但值为空」。

表单重置时回到初始状态，半选态一并清掉；外层 <fieldset disabled> 会让它一起禁用。

API

属性

属性	Attribute	类型	默认值	说明
ariaLabelText	aria-label	string | undefined	—	无障碍名称：原生 HTML 里写 aria-label，React / Vue / Angular 包装层里属性名是 ariaLabelText。 插槽里没有标签文案时（如表格的全选列）必须给；给了它就不再用插槽文案做可访问名。
checked	checked	boolean	false	是否选中。受控值：与 ptChange 配对，包装层据此生成 v-model / ngModel
disabled	disabled	boolean	false	禁用。只反映使用方自己写的值：外层原生 `<fieldset disabled>`、pt-field / pt-field-set 的禁用另经继承通道生效，不改写它
indeterminate	indeterminate	boolean	false	半选态（「部分子项被选中」）。 它只是视觉与 aria 状态，不是第三个值：点击后一律变成 checked=true， 这是原生 input[type=checkbox] 的行为，读屏用户的预期也是这样。
inheritedDisabled	inherited-disabled	boolean	false	外层 pt-field / pt-field-set 下发的禁用。内部继承通道：由它们以 attribute 维护，不建议使用方直接写。 有效禁用是 `disabled` 与它的并集；父元素只写这一条、不碰 `disabled`，读 `el.disabled` 得到的始终是使用方自己写的值
inheritedInvalid	inherited-invalid	boolean	false	外层 pt-field 下发的出错态。内部继承通道：由 pt-field 维护，不建议使用方直接写。有效出错是 `invalid` 与它的并集
inheritedRequired	inherited-required	boolean	false	外层 pt-field 下发的必填。内部继承通道：由 pt-field 维护，不建议使用方直接写。有效必填是 `required` 与它的并集
invalid	invalid	boolean	false	出错态。校验信息由使用方展示，组件只负责视觉、aria-invalid 与表单校验状态（customError）
name	name	string | undefined	—	提交表单时的字段名
required	required	boolean	false	必填：未勾选时表单校验报 valueMissing，并标注 aria-required
value	value	string	'on'	提交表单时的值，默认 "on"（与原生 checkbox 一致）。未勾选时整个字段不出现在 FormData 里

事件

事件	detail 类型	说明
ptBlur	void	内部控件失去焦点
ptChange	boolean	选中状态变化，detail 是切换后的 checked。Vue 的 v-model 与 Angular 的 ngModel 绑在它上面
ptFocus	void	内部控件获得焦点

方法

方法	说明
setFocus(options?: FocusOptions) => Promise<void>

插槽

名称	说明
（默认）	标签文案

可定制的内部元素（::part()）

part	说明
base	最外层容器（label）
box	方框本体
label	标签容器