版本：v8

ion-toggle

阴影

切换按钮是改变单个选项状态的开关。可以通过按下或滑动它们来打开或关闭它们。也可以通过设置`checked`属性以编程方式检查切换按钮。

基本用法

开/关标签

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

列表中的切换按钮

也可以通过使用Item和List组件在列表视图中使用切换按钮。

标签位置

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

对齐方式

开发人员可以使用`alignment`属性来控制标签和控件在横轴上的对齐方式。此属性反映了 flexbox 的`align-items`属性。

注意

可以使用`alignment`属性对齐堆叠的切换按钮。当标签和控件需要水平居中时，这很有用。

对齐方式

开发人员可以使用`justify`属性来控制标签和控件如何在行内排列。

主题

颜色

CSS 自定义属性

CSS 自定义属性可以与标准 CSS 相结合，以定位切换按钮的不同部分。可以直接修改切换按钮的`width`和`height`来更改轨道的大小，同时使用`--handle-width`和`--handle-height`自定义属性来自定义手柄的大小。

CSS 阴影部分

可以通过定位公开的特定阴影部分来进一步自定义切换按钮。可以对这些部分的任何 CSS 属性进行样式设置，并且也可以将它们与 CSS 自定义属性结合使用。

从旧版切换语法迁移

Ionic 在 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-toggle`需要`ion-item`才能正常工作。从 Ionic 7.0 开始，`ion-toggle`应该只在将项目放置在`ion-list`中的情况下才使用`ion-item`。此外，`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

描述	如何控制切换按钮和标签在横轴上的对齐方式。`“start”`：标签和控件将出现在 LTR 中横轴的左侧，在 RTL 中出现在右侧。`“center”`：标签和控件将出现在 LTR 和 RTL 中横轴的中心。设置此属性将更改切换按钮的`display`为`block`。
属性	`alignment`
类型	`"center" ｜ "start" ｜ undefined`
默认	`undefined`

checked

描述	如果为`true`，则切换按钮处于选中状态。
属性	`checked`
类型	`boolean`
默认	`false`

color

描述	从应用程序的颜色调色板中使用的颜色。默认选项是：`“primary”`、`“secondary”`、`“tertiary”`、`“success”`、`“warning”`、`“danger”`、`“light”`、`“medium”`和`“dark”`。有关颜色的更多信息，请参阅主题。
属性	`color`
类型	`"danger" ｜ "dark" ｜ "light" ｜ "medium" ｜ "primary" ｜ "secondary" ｜ "success" ｜ "tertiary" ｜ "warning" ｜ string ｜ undefined`
默认	`undefined`

disabled

描述	如果为`true`，则用户无法与切换按钮交互。
属性	`disabled`
类型	`boolean`
默认	`false`

enableOnOffLabels

描述	启用切换按钮内的开/关无障碍开关标签。
属性	`enable-on-off-labels`
类型	`boolean ｜ undefined`
默认	`config.get('toggleOnOffLabels')`

justify

描述	如何将标签和切换按钮打包在一条线上。`“start”`：标签和切换按钮将出现在 LTR 中的左侧，出现在 RTL 中的右侧。`“end”`：标签和切换按钮将出现在 LTR 中的右侧，出现在 RTL 中的左侧。`“space-between”`：标签和切换按钮将出现在行的两端，两元素之间有间隔。设置此属性将更改切换按钮的`display`为`block`。
属性	`justify`
类型	`"end" ｜ "space-between" ｜ "start" ｜ undefined`
默认	`undefined`

labelPlacement

描述	标签相对于输入的位置。`"start"`：标签将出现在 LTR 中切换的左侧，在 RTL 中出现在右侧。`"end"`：标签将出现在 LTR 中切换的右侧，在 RTL 中出现在左侧。`"fixed"`：标签的行为与`"start"`相同，但它还具有固定宽度。长文本将被截断，并用省略号（"..."）表示。`"stacked"`：无论方向如何，标签都将出现在切换上方。标签的对齐方式可以通过`alignment`属性进行控制。
属性	`label-placement`
类型	`"end" ｜ "fixed" ｜ "stacked" ｜ "start"`
默认	`'start'`

mode

描述	该模式确定使用哪个平台样式。
属性	`mode`
类型	`"ios" ｜ "md"`
默认	`undefined`

name

描述	控件的名称，它与表单数据一起提交。
属性	`name`
类型	`string`
默认	`this.inputId`

value

描述	切换的值并不意味着它是否被选中，请使用`checked`属性来表示。切换的值类似于`<input type="checkbox">`的值，它仅在切换参与原生`<form>`时使用。
属性	`value`
类型	`null ｜ string ｜ undefined`
默认	`'on'`

Events

Name	描述	Bubbles
`ionBlur`	当切换失去焦点时发出。	`true`
`ionChange`	当用户打开或关闭切换时发出。当以编程方式设置`checked`属性时，此事件不会发出。	`true`
`ionFocus`	当切换获得焦点时发出。	`true`

Methods

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

CSS Shadow Parts

Name	描述
`handle`	用于更改选中状态的切换手柄或旋钮。
`label`	描述切换的标签文本。
`track`	切换的背景轨道。

CSS Custom Properties

Name	描述
`--border-radius`	切换轨道的圆角
`--handle-background`	切换手柄的背景
`--handle-background-checked`	选中时的切换手柄背景
`--handle-border-radius`	切换手柄的圆角
`--handle-box-shadow`	切换手柄的阴影
`--handle-height`	切换手柄的高度
`--handle-max-height`	切换手柄的最大高度
`--handle-spacing`	切换手柄周围的水平间距
`--handle-transition`	切换手柄的过渡
`--handle-width`	切换手柄的宽度
`--track-background`	切换轨道的背景
`--track-background-checked`	选中时的切换轨道背景

Name	描述
`--border-radius`	切换轨道的圆角
`--handle-background`	切换手柄的背景
`--handle-background-checked`	选中时的切换手柄背景
`--handle-border-radius`	切换手柄的圆角
`--handle-box-shadow`	切换手柄的阴影
`--handle-height`	切换手柄的高度
`--handle-max-height`	切换手柄的最大高度
`--handle-spacing`	切换手柄周围的水平间距
`--handle-transition`	切换手柄的过渡
`--handle-width`	切换手柄的宽度
`--track-background`	切换轨道的背景
`--track-background-checked`	选中时的切换轨道背景

Slots

Name	描述
``	与切换关联的标签文本。使用 "labelPlacement" 属性来控制标签相对于切换的位置。

基本用法​

开/关标签​

列表中的切换按钮​

标签位置​

对齐方式​

对齐方式​

主题​

颜色​

CSS 自定义属性​

CSS 阴影部分​

从旧版切换语法迁移​

使用现代语法​

使用旧版语法​

接口​

ToggleChangeEventDetail​

ToggleCustomEvent​

属性​

alignment​

checked​

color​

disabled​

enableOnOffLabels​

justify​

labelPlacement​

mode​

name​

value​

Events​

Methods​

CSS Shadow Parts​

CSS Custom Properties​

Slots​

Contents

基本用法

开/关标签

列表中的切换按钮

标签位置

对齐方式

对齐方式

主题

颜色

CSS 自定义属性

CSS 阴影部分

从旧版切换语法迁移

使用现代语法

使用旧版语法

接口

ToggleChangeEventDetail

ToggleCustomEvent

属性

alignment

checked

color

disabled

enableOnOffLabels

justify

labelPlacement

mode

name

value

Events

Methods

CSS Shadow Parts

CSS Custom Properties

Slots