Switch

Switch 用于表示即时开启或关闭状态，并可选择显示选中和未选中图标。 当 Switch 仅作为另一个无障碍控件中的视觉指示器时（例如可点击的 ListItem），请使用 presentation。

飞行模式

已选中：false

尺寸

密集的工具面板可使用 size="small"；标准 Material 比例使用 size="medium"（默认值）。在默认排版和密度 0 下，轨道高度分别为 24dp 和 32dp。可在 M3VuePlugin 选项中设置 switchSize 作为应用默认值；显式指定的组件属性优先。

app.use(M3VuePlugin, { switchSize: 'small' });

全局默认值也可以使用 Vue ref，以便响应式更新。

小中

在 presentation 模式下，只有轨道占据布局空间。所属行负责提供交互和悬停反馈；--md-switch-target-size 不会为 presentation 控件增加空间。

密度

默认几何尺寸根据 body-medium 字号确定。下方尺寸针对默认排版；紧凑排版和自定义排版会先按比例缩放基准值及其范围，再应用密度。显式几何尺寸 token 会绕过此计算。

medium 轨道高度的基准值为 32dp，每个密度级别变化 1dp，并限制在 28–36dp。small 的基准值为 24dp，范围限制在 20–28dp。轨道宽度、滑块尺寸、移动内缩量、描边和内部图标都会按比例缩放。显式设置的组件 Token 会覆盖对应的尺寸；设置轨道高度时，也会据此确定默认比例。

medium 的交互和悬停目标基准尺寸为 40dp，small 为 32dp；每个密度级别变化 2dp，并在轨道上方和下方各至少保留 4dp。图标缩放和图标源校准不会影响 Switch 的几何尺寸。

密度 0密度 -2密度 -4

示例

默认

Airplane mode

Checked: false

带图标

check Airplane mode

状态

UncheckedcheckCheckedDisabled uncheckedcheckDisabled checked

参考

结构

高亮显示

元素	部件	选择器
<component>	root	[data-scope="switch"][data-part="root"] left_click鼠标左键单击复制
<input>	input条件显示	[data-scope="switch"][data-part="input"] left_click鼠标左键单击复制
<span>	control	[data-scope="switch"][data-part="control"] left_click鼠标左键单击复制
<span>	handle	[data-scope="switch"][data-part="handle"] left_click鼠标左键单击复制
<span>	icon条件显示	[data-scope="switch"][data-part="icon"] left_click鼠标左键单击复制
<span>	label条件显示	[data-scope="switch"][data-part="label"] left_click鼠标左键单击复制

属性

名称	说明	默认值	控件
size可选	Track size; inherits the configured default. SwitchSize | undefined	-	-
disabled可选	Whether the switch is disabled. boolean | undefined	false
presentation可选	Render only the visual switch. The parent must provide interaction semantics. boolean | undefined	false
checkedIcon可选	Icon name displayed when checked. string | undefined	"check"
uncheckedIcon可选	Icon name displayed when unchecked. string | undefined	-
name可选	Name attribute for the native checkbox input. string | undefined	-	-
value可选	Value attribute for the native checkbox input. string | undefined	-	-
ariaLabel可选	ARIA label forwarded to the native checkbox input. string | undefined	-	-
checked必填	- boolean	-

事件1

名称	类型	说明
update:checked	[value: boolean]	-

插槽1

名称	参数	说明
default	-	Optional label content rendered next to switch.

样式46

预览

Token	说明
--md-switch-disabled-selected-handle-colorDisabled 回退值var(--md-sys-color-surface)	Controls disabled selected handle color.
--md-switch-disabled-selected-handle-opacityDisabled 回退值1	Controls disabled selected handle opacity.
--md-switch-disabled-selected-icon-colorDisabled 回退值var(--md-sys-color-on-surface)	Controls disabled selected icon color.
--md-switch-disabled-selected-icon-opacityDisabled 回退值0.38	Controls disabled selected icon opacity.
--md-switch-disabled-selected-track-colorDisabled 回退值var(--md-sys-color-on-surface)	Controls disabled selected track color.
--md-switch-disabled-track-opacityDisabled 回退值0.12	Controls disabled track opacity.
--md-switch-disabled-unselected-handle-colorDisabled 回退值var(--md-sys-color-on-surface)	Controls disabled unselected handle color.
--md-switch-disabled-unselected-handle-opacityDisabled 回退值0.38	Controls disabled unselected handle opacity.
--md-switch-disabled-unselected-icon-colorDisabled 回退值var(--md-sys-color-surface-container-highest)	Controls disabled unselected icon color.
--md-switch-disabled-unselected-icon-opacityDisabled 回退值0.38	Controls disabled unselected icon opacity.
--md-switch-disabled-unselected-track-colorDisabled 回退值var(--md-sys-color-surface-container-highest)	Controls disabled unselected track color.
--md-switch-disabled-unselected-track-outline-colorDisabled 回退值var(--md-sys-color-on-surface)	Controls disabled unselected track outline color.
--md-switch-focus-indicator-colorFocus 回退值var(--md-sys-color-secondary)	Controls focus indicator color.
--md-switch-focus-indicator-offsetFocus 回退值var(--md-sys-state-focus-indicator-outer-offset)	Controls focus indicator offset.
--md-switch-focus-indicator-thicknessFocus 回退值var(--md-sys-state-focus-indicator-thickness)	Controls focus indicator thickness.
--md-switch-handle-shapeShape 回退值var(--md-sys-shape-corner-full)	Controls handle shape.
--md-switch-pressed-handle-heightState 回退值Resolved track height × 28 / 32	Controls pressed handle height.
--md-switch-pressed-handle-widthState 回退值Resolved track height × 28 / 32	Controls pressed handle width.
--md-switch-selected-handle-colorState 回退值var(--md-sys-color-on-primary)	Controls selected handle color.
--md-switch-selected-handle-heightState 回退值Resolved track height × 24 / 32	Controls selected handle height.
--md-switch-selected-handle-widthState 回退值Resolved track height × 24 / 32	Controls selected handle width.
--md-switch-selected-hover-handle-colorState 回退值var(--md-sys-color-primary-container)	Controls selected hover handle color.
--md-switch-selected-hover-track-colorState 回退值var(--md-sys-color-primary)	Controls selected hover track color.
--md-switch-selected-icon-colorState 回退值var(--md-sys-color-primary)	Controls selected icon color.
--md-switch-selected-icon-sizeState 回退值Resolved track height × 16 / 32	Controls selected icon size.
--md-switch-selected-pressed-handle-colorState 回退值var(--md-sys-color-primary-container)	Controls selected pressed handle color.
--md-switch-selected-pressed-track-colorState 回退值var(--md-sys-color-primary)	Controls selected pressed track color.
--md-switch-selected-track-colorState 回退值var(--md-sys-color-primary)	Controls selected track color.
--md-switch-target-sizeLayout 回退值Size baseline + 2dp per density step; at least track height + 8dp; presentation uses track height	Controls the minimum interaction target height.
--md-switch-track-heightLayout 回退值Size, typography and density (small: 24dp; medium: 32dp at default typography and density 0)	Controls track height.
--md-switch-track-outline-widthLayout 回退值Resolved track height / 16	Controls track outline width.
--md-switch-track-shapeShape 回退值var(--md-sys-shape-corner-full)	Controls track shape.
--md-switch-track-widthLayout 回退值Resolved track height × 52 / 32	Controls track width.
--md-switch-unselected-handle-colorState 回退值var(--md-sys-color-outline)	Controls unselected handle color.
--md-switch-unselected-handle-heightState 回退值Resolved track height × 16 / 32	Controls unselected handle height.
--md-switch-unselected-handle-widthState 回退值Resolved track height × 16 / 32	Controls unselected handle width.
--md-switch-unselected-hover-handle-colorState 回退值var(--md-sys-color-on-surface-variant)	Controls unselected hover handle color.
--md-switch-unselected-hover-track-colorState 回退值var(--md-sys-color-surface-container-highest)	Controls unselected hover track color.
--md-switch-unselected-icon-colorState 回退值var(--md-sys-color-surface-container-highest)	Controls unselected icon color.
--md-switch-unselected-icon-sizeState 回退值Resolved track height × 16 / 32	Controls unselected icon size.
--md-switch-unselected-pressed-handle-colorState 回退值var(--md-sys-color-on-surface-variant)	Controls unselected pressed handle color.
--md-switch-unselected-pressed-track-colorState 回退值var(--md-sys-color-surface-container-highest)	Controls unselected pressed track color.
--md-switch-unselected-track-colorState 回退值var(--md-sys-color-surface-container-highest)	Controls unselected track color.
--md-switch-unselected-track-outline-colorState 回退值var(--md-sys-color-outline)	Controls unselected track outline color.
--md-switch-with-icon-handle-heightLayout 回退值Resolved track height × 24 / 32	Controls with icon handle height.
--md-switch-with-icon-handle-widthLayout 回退值Resolved track height × 24 / 32	Controls with icon handle width.