Toggle 切换按钮

按下 / 弹起两态的按钮，表示「这个格式 / 模式当前是否生效」，如编辑器工具栏里的「加粗」。 立即生效的设置项开关请用 Switch。

基础用法

点击在按下 / 弹起之间切换，受控值是 pressed + ptChange。按下态是浅灰底 + 最强文字色；outline 变体多一圈 1px 描边。

<pt-toggle>加粗</pt-toggle>
<pt-toggle pressed>斜体</pt-toggle>
<pt-toggle variant="outline">下划线</pt-toggle>
<pt-toggle variant="outline" pressed>删除线</pt-toggle>

尺寸

三档控件刻度：24 / 32 / 40。lg 档图标放大到 20px。

<pt-toggle size="sm" variant="outline">小</pt-toggle>
<pt-toggle size="md" variant="outline">中</pt-toggle>
<pt-toggle size="lg" variant="outline">大</pt-toggle>

纯图标与禁用

纯图标时必须给 aria-label（包装层里是 ariaLabelText），否则读屏只会读出「切换按钮」。

<pt-toggle aria-label="加粗">
  <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
    <path d="M6 12h9a4 4 0 0 1 0 8H7a1 1 0 0 1-1-1V5a1 1 0 0 1 1-1h7a4 4 0 0 1 0 8"></path>
  </svg>
</pt-toggle>
<pt-toggle aria-label="斜体" pressed>
  <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
    <line x1="19" x2="10" y1="4" y2="4"></line>
    <line x1="14" x2="5" y1="20" y2="20"></line>
    <line x1="15" x2="9" y1="4" y2="20"></line>
  </svg>
</pt-toggle>
<pt-toggle disabled>不可用</pt-toggle>
<pt-toggle disabled pressed>不可用（按下）</pt-toggle>

受控值

受控值是 pressed + ptChange：用户点击切换后发 ptChange，detail 是切换后的 pressed； 外部改写 pressed 不发事件。Vue 的 v-model、Angular 的 [(ngModel)] 都绑在 pressed 上。

<pt-toggle id="bold">加粗</pt-toggle>
<script>
  document.getElementById('bold').addEventListener('ptChange', e => console.log(e.detail));
</script>

放进 pt-toggle-group（直接子元素）时，按下态由组统一管理：点击不自行切换、也不发自己的 ptChange， 由组发出组的 ptChange。这时要给每一项写 value —— 组按它认领按下态；value 只在组内有意义，单独使用时不起作用。

键盘操作

按键	行为
Space	切换
Enter	切换

无障碍

内部是原生 <button type="button">，按下态写在 aria-pressed 上；放在切换按钮组里（包括 type="single"） 也保持这一语义（见 ToggleGroup 的无障碍）。纯图标时必须给 aria-label —— 在 React / Vue / Angular 包装层里属性名是 ariaLabelText。

API

属性

属性	Attribute	类型	默认值	说明
ariaLabelText	aria-label	string | undefined	—	无障碍名称：原生 HTML 里写 aria-label，React / Vue / Angular 包装层里属性名是 ariaLabelText。 纯图标的切换按钮**必须**给，否则读屏用户只会听到「切换按钮」。
disabled	disabled	boolean	false	禁用。放在 pt-toggle-group 里时，组的 `disabled` 也会禁用它（组级优先，不改写本属性）
inheritedDisabled	inherited-disabled	boolean	false	外层 pt-field-set 下发的禁用。内部继承通道：由它以 attribute 维护，不建议使用方直接写。 有效禁用是 `disabled` 与它的并集；父元素只写这一条、不碰 `disabled`，读 `el.disabled` 得到的始终是使用方自己写的值
pressed	pressed	boolean	false	是否按下。受控值：与 ptChange 配对，包装层据此生成 v-model / ngModel。 在 pt-toggle-group 里由组按它的 `value` 回写，外部改了会被组改回去
size	size	"lg" | "md" | "sm"	'md'	尺寸档位。三档对应 24 / 32 / 40 的控件刻度。在写了 size 的 pt-toggle-group 里以组的为准
value	value	string | undefined	—	在 pt-toggle-group 里代表这一项的值：组的 `value` 里出现它就按下，点击时组按它改写 `value`。 同一组里要唯一；multiple 组写成 HTML attribute 时 `value` 以逗号分隔，所以值本身不要含逗号。 **只在组内有意义**，单独使用时不参与任何行为，也不提交表单。组内缺了它的项不能被选中
variant	variant	"default" | "outline"	'default'	视觉变体：default 透明底；outline 带 1px 描边。在写了 variant 的 pt-toggle-group 里以组的为准

事件

事件	detail 类型	说明
ptChange	boolean	用户点击切换后触发，detail 是切换后的 pressed。外部改写 pressed 不触发。 Vue 的 v-model 与 Angular 的 ngModel 绑在它上面。在 pt-toggle-group 里不触发（由组发）

插槽

名称	说明
（默认）	按钮内容：文字、图标（svg 默认 16px，lg 档 20px）或二者组合。纯图标时请给 aria-label

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

part	说明
base	内部的 button 元素

CSS 变量

变量	说明
--pt-toggle-radius	圆角，默认取控件档位（md / lg 为 --pt-radius-md，sm 为 --pt-radius-sm）