ion-toggle

shadow

开关（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 7.0 引入了一种更简洁的开关语法。这种新语法减少了设置开关所需的模板代码，解决了可访问性问题，并改善了开发体验。

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

使用现代语法

使用现代语法涉及移除 ion-label，并直接将标签传递到 ion-toggle 内部。标签的位置可以通过 ion-toggle 上的 labelPlacement 属性进行配置。标签和控件在一行上的排列方式可以通过 ion-toggle 上的 justify 属性来控制。

JavaScript

<!-- 基础用法 -->

<!-- 旧写法 -->
<ion-item>
  <ion-label>通知</ion-label>
  <ion-toggle></ion-toggle>
</ion-item>

<!-- 新写法 -->
<ion-item>
  <ion-toggle>通知</ion-toggle>
</ion-item>

<!-- 固定标签 -->

<!-- 旧写法 -->
<ion-item>
  <ion-label position="fixed">通知</ion-label>
  <ion-toggle></ion-toggle>
</ion-item>

<!-- 新写法 -->
<ion-item>
  <ion-toggle label-placement="fixed">通知</ion-toggle>
</ion-item>

<!-- 开关在前，标签在后 -->

<!-- 旧写法 -->
<ion-item>
  <ion-label slot="end">通知</ion-label>
  <ion-toggle></ion-toggle>
</ion-item>

<!-- 新写法 -->
<ion-item>
  <ion-toggle label-placement="end">通知</ion-toggle>
</ion-item>

Angular

<!-- 基础用法 -->

<!-- 旧写法 -->
<ion-item>
  <ion-label>通知</ion-label>
  <ion-toggle></ion-toggle>
</ion-item>

<!-- 新写法 -->
<ion-item>
  <ion-toggle>通知</ion-toggle>
</ion-item>

<!-- 固定标签 -->

<!-- 旧写法 -->
<ion-item>
  <ion-label position="fixed">通知</ion-label>
  <ion-toggle></ion-toggle>
</ion-item>

<!-- 新写法 -->
<ion-item>
  <ion-toggle label-placement="fixed">通知</ion-toggle>
</ion-item>

<!-- 开关在前，标签在后 -->

<!-- 旧写法 -->
<ion-item>
  <ion-label slot="end">通知</ion-label>
  <ion-toggle></ion-toggle>
</ion-item>

<!-- 新写法 -->
<ion-item>
  <ion-toggle label-placement="end">通知</ion-toggle>
</ion-item>

React

{/* 基础用法 */}

{/* 旧写法 */}
<IonItem>
  <IonLabel>通知</IonLabel>
  <IonToggle></IonToggle>
</IonItem>

{/* 新写法 */}
<IonItem>
  <IonToggle>通知</IonToggle>
</IonItem>

{/* 固定标签 */}

{/* 旧写法 */}
<IonItem>
  <IonLabel position="fixed">通知</IonLabel>
  <IonToggle></IonToggle>
</IonItem>

{/* 新写法 */}
<IonItem>
  <IonToggle labelPlacement="fixed">通知</IonToggle>
</IonItem>

{/* 开关在前，标签在后 */}

{/* 旧写法 */}
<IonItem>
  <IonLabel slot="end">通知</IonLabel>
  <IonToggle></IonToggle>
</IonItem>

{/* 新写法 */}
<IonItem>
  <IonToggle labelPlacement="end">通知</IonToggle>
</IonItem>

Vue

<!-- 基础用法 -->

<!-- 旧写法 -->
<ion-item>
  <ion-label>通知</ion-label>
  <ion-toggle></ion-toggle>
</ion-item>

<!-- 新写法 -->
<ion-item>
  <ion-toggle>通知</ion-toggle>
</ion-item>

<!-- 固定标签 -->

<!-- 旧写法 -->
<ion-item>
  <ion-label position="fixed">通知</ion-label>
  <ion-toggle></ion-toggle>
</ion-item>

<!-- 新写法 -->
<ion-item>
  <ion-toggle label-placement="fixed">通知</ion-toggle>
</ion-item>

<!-- 开关在前，标签在后 -->

<!-- 旧写法 -->
<ion-item>
  <ion-label slot="end">通知</ion-label>
  <ion-toggle></ion-toggle>
</ion-item>

<!-- 新写法 -->
<ion-item>
  <ion-toggle label-placement="end">通知</ion-toggle>
</ion-item>

备注

在 Ionic 的早期版本中，ion-toggle 需要依赖 ion-item 才能正常工作。从 Ionic 7.0 开始，只有当 ion-item 被放置在 ion-list 中时，才需要在其中使用 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

Description	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.
Attribute	alignment
Type	"center" ｜ "start"
Default	'center'

checked

Description	If true, the toggle is selected.
Attribute	checked
Type	boolean
Default	false

color

Description	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.
Attribute	color
Type	"danger" ｜ "dark" ｜ "light" ｜ "medium" ｜ "primary" ｜ "secondary" ｜ "success" ｜ "tertiary" ｜ "warning" ｜ string ｜ undefined
Default	undefined

disabled

Description	If true, the user cannot interact with the toggle.
Attribute	disabled
Type	boolean
Default	false

enableOnOffLabels

Description	Enables the on/off accessibility switch labels within the toggle.
Attribute	enable-on-off-labels
Type	boolean ｜ undefined
Default	config.get('toggleOnOffLabels')

justify

Description	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.
Attribute	justify
Type	"end" ｜ "space-between" ｜ "start"
Default	'space-between'

labelPlacement

Description	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.
Attribute	label-placement
Type	"end" ｜ "fixed" ｜ "stacked" ｜ "start"
Default	'start'

legacy

Description	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.
Attribute	legacy
Type	boolean ｜ undefined
Default	undefined

mode

Description	The mode determines which platform styles to use. This is a virtual property that is set once during initialization and will not update if you change its value after the initial render.
Attribute	mode
Type	"ios" ｜ "md"
Default	undefined

name

Description	The name of the control, which is submitted with the form data.
Attribute	name
Type	string
Default	this.inputId

value

Description	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>.
Attribute	value
Type	null ｜ string ｜ undefined
Default	'on'

事件

Name	Description	Bubbles
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

方法

No public methods available for this component.

CSS 影子部件

Name	Description
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	Description
--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	Description
``	The label text to associate with the toggle. Use the "labelPlacement" property to control where the label is placed relative to the toggle.