ion-toggle

shadow

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

🌐 Toggles are switches that change the state of a single option. They can be switched on or off by pressing or swiping them. Toggles can also be checked programmatically by setting the checked property.

基本用法

🌐 Basic Usage

开/关标签

🌐 On / Off Labels

通过设置 enableOnOffLabels 属性，开关可以启用开/关标签。这对于无障碍性非常重要，因为它可以更容易地区分已选中和未选中的开关。

🌐 Toggles can enable on/off labels by setting the enableOnOffLabels property. This is important for accessibility as it makes it easier to differentiate between a checked and unchecked toggle.

在列表中切换

🌐 Toggles in a List

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

🌐 Toggles can also be used in a list view by using the Item and List components.

标签放置

🌐 Label Placement

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

🌐 Developers can use the labelPlacement property to control how the label is placed relative to the control.

对齐

🌐 Alignment

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

🌐 Developers can use the alignment property to control how the label and control are aligned on the cross axis. This property mirrors the flexbox align-items property.

note

可以使用 alignment 属性对堆叠切换进行对齐。当标签和控件需要水平居中时，这可能会很有用。

齐行

🌐 Justification

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

🌐 Developers can use the justify property to control how the label and control are packed on a line.

辅助程序和错误文本

🌐 Helper & Error Text

帮助文本和错误文本可以在使用 helperText 和 errorText 属性的切换中使用。除非将 ion-invalid 和 ion-touched 类添加到 ion-toggle 中，否则错误文本将不会显示。这确保了在用户有机会输入数据之前不会显示错误。

🌐 Helper and error text can be used inside of a toggle with the helperText and errorText property. The error text will not be displayed unless the ion-invalid and ion-touched classes are added to the ion-toggle. This ensures errors are not shown before the user has a chance to enter data.

在 Angular 中，这通过表单验证自动补齐。在 JavaScript、React 和 Vue 中，需要根据你自己的验证手动添加类。

🌐 In Angular, this is done automatically through form validation. In JavaScript, React and Vue, the class needs to be manually added based on your own validation.

主题化

🌐 Theming

颜色

🌐 Colors

CSS 自定义属性

🌐 CSS Custom Properties

CSS 自定义属性可以与标准 CSS 结合使用，以针对切换控件的不同部分。我们可以直接修改切换控件的 width 和 height 来改变轨道的大小，同时使用 --handle-width 和 --handle-height 自定义属性来定制滑块的大小。

🌐 CSS custom properties can be combined with standard CSS to target different parts of a toggle. We can modify the width and height of the toggle directly to change the size of the track, while using the --handle-width and --handle-height custom properties to customize the handle size.

CSS 阴影部分

🌐 CSS Shadow Parts

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

🌐 We can further customize toggle by targeting specific shadow parts that are exposed. Any CSS property on these parts can be styled and they can also be combined with CSS custom properties.

接口

🌐 Interfaces

ToggleChangeEventDetail

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

ToggleCustomEvent

虽然不是必需的，但可以使用此接口替代 CustomEvent 接口，以便对从此组件发出的 Ionic 事件进行更强类型的处理。

🌐 While not required, this interface can be used in place of the CustomEvent interface for stronger typing with Ionic events emitted from this component.

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

属性

🌐 Properties

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. Setting this property will change the toggle display to block.
Attribute	alignment
Type	"center" ｜ "start" ｜ undefined
Default	undefined

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')

errorText

Description	Text that is placed under the toggle label and displayed when an error is detected.
Attribute	error-text
Type	string ｜ undefined
Default	undefined

helperText

Description	Text that is placed under the toggle label and displayed when no error is detected.
Attribute	helper-text
Type	string ｜ undefined
Default	undefined

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. Setting this property will change the toggle display to block.
Attribute	justify
Type	"end" ｜ "space-between" ｜ "start" ｜ undefined
Default	undefined

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'

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

required

Description	If true, screen readers will announce it as a required field. This property works only for accessibility purposes, it will not prevent the form from submitting if the value is invalid.
Attribute	required
Type	boolean
Default	false

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'

事件

🌐 Events

Name	Description	Bubbles
ionBlur	Emitted when the toggle loses focus.	true
ionChange	Emitted when the user switches the toggle on or off. This event will not emit when programmatically setting the checked property.	true
ionFocus	Emitted when the toggle has focus.	true

方法

🌐 Methods

No public methods available for this component.

CSS 阴影部分

🌐 CSS Shadow Parts

Name	Description
error-text	Supporting text displayed beneath the toggle label when the toggle is invalid and touched.
handle	The toggle handle, or knob, used to change the checked state.
helper-text	Supporting text displayed beneath the toggle label when the toggle is valid.
label	The label text describing the toggle.
supporting-text	Supporting text displayed beneath the toggle label.
track	The background track of the toggle.

CSS 自定义属性

🌐 CSS Custom Properties

iOS

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

MD

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

插槽

🌐 Slots

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.