Switch 开关

立即生效的开关：改了就生效，没有「提交」这一步。待提交的勾选请用 Checkbox。

基础用法

立即生效的开关：改了就生效，没有「提交」这一步。受控值同 checkbox：checked + ptChange。

<pt-switch>开启通知</pt-switch>
<pt-switch checked>已开启</pt-switch>

尺寸

sm 给密集列表 / 表格用：一行只有 32–40px 高时，20px 的开关会顶满整行。

<pt-switch>md（默认）</pt-switch>
<pt-switch size="sm">sm</pt-switch>

禁用

外层 <fieldset disabled> 也会让它一起禁用。

<pt-switch disabled>禁用</pt-switch>
<pt-switch disabled checked>禁用且已开启</pt-switch>

什么时候用哪个

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

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

键盘操作

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

无障碍

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

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

表单里的值

未打开时提交 null（字段不出现在 FormData 里），打开时提交 value（默认 "on"）， 与原生 checkbox 一致。表单重置时回到初始状态；外层 <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 的禁用另经继承通道生效，不改写它
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
size	size	"md" | "sm"	'md'	sm 给密集列表 / 表格用：一行只有 32–40px 高时，20px 的开关会顶满整行
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）
label
thumb	拇指
track	轨道