ion-toggle

陰影

切換開關是用於變更單一選項狀態的開關。可以透過按下或滑動來開啟或關閉。也可以透過程式碼設定 checked 屬性來選取切換開關。

基本用法

開啟/關閉標籤

切換開關可以透過設定 enableOnOffLabels 屬性來啟用開啟/關閉標籤。這對協助工具來說很重要，因為這樣可以更容易區分已選取和未選取的切換開關。

清單中的切換開關

切換開關也可以透過使用 項目 和 清單 元件在清單視圖中使用。

標籤位置

開發人員可以使用 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

<!-- 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>

Angular

<!-- 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>

React

{/* 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>

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>

注意

在舊版的 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

描述	如何在交叉軸上控制切換開關和標籤的對齊方式。"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'

事件

名稱	描述	冒泡
ionBlur	當切換開關失去焦點時觸發。	true
ionChange	當使用者切換開關的開啟或關閉時觸發。 當以程式方式設定 checked 屬性時，此事件不會觸發。	true
ionFocus	當切換開關獲得焦點時觸發。	true

方法

此元件沒有可用的公開方法。

CSS Shadow Parts

名稱	描述
handle	用於更改勾選狀態的切換開關手柄或旋鈕。
label	描述切換開關的標籤文字。
track	切換開關的背景軌道。

CSS 自訂屬性

iOS

名稱	描述
--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	勾選時切換開關軌道的背景

MD

名稱	描述
--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	勾選時切換開關軌道的背景

插槽

名稱	描述
``	要與切換開關關聯的標籤文字。使用 "labelPlacement" 屬性來控制標籤相對於切換開關的放置位置。