版本：v6

ion-toggle

shadow

切换开关（Toggle）是更改单个选项状态的开关。可以通过按下或滑动来打开或关闭它们。切换开关也可以通过设置 checked 属性以编程方式选中。

基本用法

开/关标签

切换开关可以通过设置 enableOnOffLabels 属性来启用开/关标签。这对无障碍访问很重要，因为它使已选中和未选中的切换开关更容易区分。

列表中的切换开关

切换开关也可以通过使用项目（Item）和列表（List）组件在列表视图中使用。

标签位置

开发者可以使用 labelPlacement 属性控制标签相对于控件的位置。

对齐

开发者可以使用 alignment 属性控制标签和控件在交叉轴上的对齐方式。此属性对应 flexbox 的 align-items 属性。

备注

堆叠的切换开关可以使用 alignment 属性进行对齐。当标签和控件需要在水平方向上居中时，这很有用。

排列（Justify）

开发者可以使用 justify 属性控制标签和控件在一行上的排列方式。

主题

颜色

CSS 自定义属性

CSS 自定义属性可以与标准 CSS 结合使用，以定位切换开关的不同部分。我们可以直接修改切换开关的 width 和 height 来改变轨道的尺寸，同时使用 --handle-width 和 --handle-height 自定义属性来自定义手柄尺寸。

CSS 阴影部分

我们可以通过定位暴露的特定阴影部分来进一步自定义切换开关。这些部分上的任何 CSS 属性都可以设置样式，并且也可以与 CSS 自定义属性结合使用。

从旧版切换开关语法迁移

Ionic 7.0 引入了更简单的切换开关语法。这种新语法减少了设置切换开关所需的样板代码，解决了无障碍访问问题，并改善了开发者体验。

虽然开发者可以继续使用旧版语法，但我们建议尽快迁移。

使用现代语法

使用现代语法需要移除 ion-label 并将标签直接传递给 ion-toggle。标签的位置可以使用 ion-toggle 上的 labelPlacement 属性进行配置。标签和控件在一行上的排列方式可以使用 ion-toggle 上的 justify 属性控制。

JavaScript
Angular
React
Vue

<!-- Basic -->

<!-- Before -->
<ion-item>
  <ion-label>Notifications</ion-label>
  <ion-toggle></ion-toggle>
</ion-item>

<!-- After -->
<ion-item>
  <ion-toggle>Notifications</ion-toggle>
</ion-item>

<!-- Fixed Labels -->

<!-- Before -->
<ion-item>
  <ion-label position="fixed">Notifications</ion-label>
  <ion-toggle></ion-toggle>
</ion-item>

<!-- After -->
<ion-item>
  <ion-toggle label-placement="fixed">Notifications</ion-toggle>
</ion-item>

<!-- Toggle at the start of line, Label at the end of line -->

<!-- Before -->
<ion-item>
  <ion-label slot="end">Notifications</ion-label>
  <ion-toggle></ion-toggle>
</ion-item>

<!-- After -->
<ion-item>
  <ion-toggle label-placement="end">Notifications</ion-toggle>
</ion-item>

<!-- Basic -->

<!-- Before -->
<ion-item>
  <ion-label>Notifications</ion-label>
  <ion-toggle></ion-toggle>
</ion-item>

<!-- After -->
<ion-item>
  <ion-toggle>Notifications</ion-toggle>
</ion-item>

<!-- Fixed Labels -->

<!-- Before -->
<ion-item>
  <ion-label position="fixed">Notifications</ion-label>
  <ion-toggle></ion-toggle>
</ion-item>

<!-- After -->
<ion-item>
  <ion-toggle label-placement="fixed">Notifications</ion-toggle>
</ion-item>

<!-- Toggle at the start of line, Label at the end of line -->

<!-- Before -->
<ion-item>
  <ion-label slot="end">Notifications</ion-label>
  <ion-toggle></ion-toggle>
</ion-item>

<!-- After -->
<ion-item>
  <ion-toggle label-placement="end">Notifications</ion-toggle>
</ion-item>

{/* Basic */}

{/* Before */}
<IonItem>
  <IonLabel>Notifications</IonLabel>
  <IonToggle></IonToggle>
</IonItem>

{/* After */}
<IonItem>
  <IonToggle>Notifications</IonToggle>
</IonItem>

{/* Fixed Labels */}

{/* Before */}
<IonItem>
  <IonLabel position="fixed">Notifications</IonLabel>
  <IonToggle></IonToggle>
</IonItem>

{/* After */}
<IonItem>
  <IonToggle labelPlacement="fixed">Notifications</IonToggle>
</IonItem>

{/* Toggle at the start of line, Label at the end of line */}

{/* Before */}
<IonItem>
  <IonLabel slot="end">Notifications</IonLabel>
  <IonToggle></IonToggle>
</IonItem>

{/* After */}
<IonItem>
  <IonToggle labelPlacement="end">Notifications</IonToggle>
</IonItem>

<!-- Basic -->

<!-- Before -->
<ion-item>
  <ion-label>Notifications</ion-label>
  <ion-toggle></ion-toggle>
</ion-item>

<!-- After -->
<ion-item>
  <ion-toggle>Notifications</ion-toggle>
</ion-item>

<!-- Fixed Labels -->

<!-- Before -->
<ion-item>
  <ion-label position="fixed">Notifications</ion-label>
  <ion-toggle></ion-toggle>
</ion-item>

<!-- After -->
<ion-item>
  <ion-toggle label-placement="fixed">Notifications</ion-toggle>
</ion-item>

<!-- Toggle at the start of line, Label at the end of line -->

<!-- Before -->
<ion-item>
  <ion-label slot="end">Notifications</ion-label>
  <ion-toggle></ion-toggle>
</ion-item>

<!-- After -->
<ion-item>
  <ion-toggle label-placement="end">Notifications</ion-toggle>
</ion-item>

备注

在之前的 Ionic 版本中，ion-item 是 ion-toggle 正常运行所必需的。从 Ionic 7.0 开始，仅当项目放置在 ion-list 中时，才应在 ion-item 中使用 ion-toggle。此外，ion-toggle 的正常运行不再需要 ion-item。

使用旧版语法

Ionic 使用启发式方法检测应用是否在使用现代切换开关语法。在某些情况下，继续使用旧版语法可能更可取。开发者可以将 ion-toggle 上的 legacy 属性设置为 true，以强制该切换开关实例使用旧版语法。

接口

ToggleChangeEventDetail

interface ToggleChangeEventDetail<T = any> {
  value: T;
  checked: boolean;
}

ToggleCustomEvent

虽然不是必需的，但此接口可以替代 CustomEvent 接口，为此组件发出的 Ionic 事件提供更强的类型支持。

interface ToggleCustomEvent<T = any> extends CustomEvent {
  detail: ToggleChangeEventDetail<T>;
  target: HTMLIonToggleElement;
}

属性

alignment

说明	How to control the alignment of the toggle and label on the cross axis. `"start"`: The label and control will appear on the left of the cross axis in LTR, and on the right side in RTL. `"center"`: The label and control will appear at the center of the cross axis in both LTR and RTL.
属性	`alignment`
类型	`"center" ｜ "start"`
默认值	`'center'`

checked

说明	If `true`, the toggle is selected.
属性	`checked`
类型	`boolean`
默认值	`false`

color

说明	The color to use from your application's color palette. Default options are: `"primary"`, `"secondary"`, `"tertiary"`, `"success"`, `"warning"`, `"danger"`, `"light"`, `"medium"`, and `"dark"`. For more information on colors, see theming.
属性	`color`
类型	`"danger" ｜ "dark" ｜ "light" ｜ "medium" ｜ "primary" ｜ "secondary" ｜ "success" ｜ "tertiary" ｜ "warning" ｜ string ｜ undefined`
默认值	`undefined`

disabled

说明	If `true`, the user cannot interact with the toggle.
属性	`disabled`
类型	`boolean`
默认值	`false`

enableOnOffLabels

说明	Enables the on/off accessibility switch labels within the toggle.
属性	`enable-on-off-labels`
类型	`boolean ｜ undefined`
默认值	`config.get('toggleOnOffLabels')`

justify

说明	How to pack the label and toggle within a line. `"start"`: The label and toggle will appear on the left in LTR and on the right in RTL. `"end"`: The label and toggle will appear on the right in LTR and on the left in RTL. `"space-between"`: The label and toggle will appear on opposite ends of the line with space between the two elements.
属性	`justify`
类型	`"end" ｜ "space-between" ｜ "start"`
默认值	`'space-between'`

labelPlacement

说明	Where to place the label relative to the input. `"start"`: The label will appear to the left of the toggle in LTR and to the right in RTL. `"end"`: The label will appear to the right of the toggle in LTR and to the left in RTL. `"fixed"`: The label has the same behavior as `"start"` except it also has a fixed width. Long text will be truncated with ellipses ("..."). `"stacked"`: The label will appear above the toggle regardless of the direction. The alignment of the label can be controlled with the `alignment` property.
属性	`label-placement`
类型	`"end" ｜ "fixed" ｜ "stacked" ｜ "start"`
默认值	`'start'`

legacy

说明	Set the `legacy` property to `true` to forcibly use the legacy form control markup. Ionic will only opt components in to the modern form markup when they are using either the `aria-label` attribute or the default slot that contains the label text. As a result, the `legacy` property should only be used as an escape hatch when you want to avoid this automatic opt-in behavior. Note that this property will be removed in an upcoming major release of Ionic, and all form components will be opted-in to using the modern form markup.
属性	`legacy`
类型	`boolean ｜ undefined`
默认值	`undefined`

mode

说明	The mode determines which platform styles to use. 这是一个虚拟属性，在初始化时设置一次，之后更改其值不会更新组件。
属性	`mode`
类型	`"ios" ｜ "md"`
默认值	`undefined`

name

说明	The name of the control, which is submitted with the form data.
属性	`name`
类型	`string`
默认值	`this.inputId`

value

说明	The value of the toggle does not mean if it's checked or not, use the `checked` property for that. The value of a toggle is analogous to the value of a `<input type="checkbox">`, it's only used when the toggle participates in a native `<form>`.
属性	`value`
类型	`null ｜ string ｜ undefined`
默认值	`'on'`

事件

Name	说明	冒泡
`ionBlur`	Emitted when the toggle loses focus.	`true`
`ionChange`	Emitted when the user switches the toggle on or off. Does not emit when programmatically changing the value of the `checked` property.	`true`
`ionFocus`	Emitted when the toggle has focus.	`true`

方法

该组件没有可用的公共方法。

CSS 阴影部分

Name	说明
`handle`	The toggle handle, or knob, used to change the checked state.
`label`	The label text describing the toggle.
`track`	The background track of the toggle.

CSS 自定义属性

Name	说明
`--border-radius`	Border radius of the toggle track
`--handle-background`	Background of the toggle handle
`--handle-background-checked`	Background of the toggle handle when checked
`--handle-border-radius`	Border radius of the toggle handle
`--handle-box-shadow`	Box shadow of the toggle handle
`--handle-height`	Height of the toggle handle
`--handle-max-height`	Maximum height of the toggle handle
`--handle-spacing`	Horizontal spacing around the toggle handle
`--handle-transition`	Transition of the toggle handle
`--handle-width`	Width of the toggle handle
`--track-background`	Background of the toggle track
`--track-background-checked`	Background of the toggle track when checked

插槽

Name	说明
	The label text to associate with the toggle. Use the "labelPlacement" property to control where the label is placed relative to the toggle.

基本用法​

开/关标签​

列表中的切换开关​

标签位置​

对齐​

排列（Justify）​

主题​

颜色​

CSS 自定义属性​

CSS 阴影部分​

从旧版切换开关语法迁移​

使用现代语法​

使用旧版语法​

接口​

ToggleChangeEventDetail​

ToggleCustomEvent​

属性​

alignment​

checked​

color​

disabled​

enableOnOffLabels​

justify​

labelPlacement​

legacy​

mode​

name​

value​

事件​

方法​

CSS 阴影部分​

CSS 自定义属性​

插槽​

目录

基本用法

开/关标签

列表中的切换开关

标签位置

对齐

排列（Justify）

主题

颜色

CSS 自定义属性

CSS 阴影部分

从旧版切换开关语法迁移

使用现代语法

使用旧版语法

接口

ToggleChangeEventDetail

ToggleCustomEvent

属性

alignment

checked

color

disabled

enableOnOffLabels

justify

labelPlacement

legacy

mode

name

value

事件

方法

CSS 阴影部分

CSS 自定义属性

插槽