版本：v8

ion-checkbox

陰影

核取方塊允許從一組選項中選擇多個選項。啟用時，它們會顯示為已勾選（打勾）。點擊核取方塊將切換 checked 屬性。也可以透過程式設計方式設定 checked 屬性來勾選它們。

基本用法

標籤放置

開發人員可以使用 labelPlacement 屬性來控制標籤相對於控制項的放置方式。此屬性會鏡像 flexbox 的 flex-direction 屬性。

對齊

開發人員可以使用 alignment 屬性來控制標籤和控制項在交叉軸上的對齊方式。此屬性會鏡像 flexbox 的 align-items 屬性。

注意

堆疊的核取方塊可以使用 alignment 屬性對齊。當標籤和控制項需要水平置中時，這會很有用。

對齊方式

開發人員可以使用 justify 屬性來控制標籤和控制項在一行上的排列方式。此屬性會鏡像 flexbox 的 justify-content 屬性。

注意

ion-item 僅在示範中用於強調 justify 的運作方式。它不是讓 justify 正確運作的必要條件。

不確定狀態的核取方塊

標籤內的連結

核取方塊標籤有時會附帶連結。這些連結可以提供與核取方塊相關的更多資訊。然而，點擊連結不應勾選核取方塊。為了實現這一點，我們可以使用 stopPropagation 來防止點擊事件冒泡。使用這種方法時，標籤的其餘部分仍然可以點擊。

主題

CSS 自訂屬性

介面

CheckboxChangeEventDetail

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

CheckboxCustomEvent

雖然不是必需的，但這個介面可以取代 CustomEvent 介面，以便對此元件發出的 Ionic 事件進行更強的類型檢查。

interface CheckboxCustomEvent<T = any> extends CustomEvent {
  detail: CheckboxChangeEventDetail<T>;
  target: HTMLIonCheckboxElement;
}

從舊版核取方塊語法遷移

Ionic 7.0 中引入了更簡單的核取方塊語法。這個新的語法減少了設定核取方塊所需的樣板程式碼、解決了輔助功能問題並改善了開發人員體驗。

開發人員可以一次執行一個核取方塊的遷移。雖然開發人員可以繼續使用舊版語法，但我們建議盡快遷移。

使用現代語法

使用現代語法涉及移除 ion-label 並直接將標籤傳遞到 ion-checkbox 內。可以使用 ion-checkbox 上的 labelPlacement 屬性來設定標籤的放置位置。可以使用 ion-checkbox 上的 justify 屬性來控制標籤和控制項在一行上的排列方式。

JavaScript
Angular
React
Vue

<!-- Basic -->

<!-- Before -->
<ion-item>
  <ion-label>Checkbox Label</ion-label>
  <ion-checkbox></ion-checkbox>
</ion-item>

<!-- After -->
<ion-item>
  <ion-checkbox>Checkbox Label</ion-checkbox>
</ion-item>

<!-- Fixed Labels -->

<!-- Before -->
<ion-item>
  <ion-label position="fixed">Checkbox Label</ion-label>
  <ion-checkbox></ion-checkbox>
</ion-item>

<!-- After -->
<ion-item>
  <ion-checkbox label-placement="fixed">Checkbox Label</ion-checkbox>
</ion-item>

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

<!-- Before -->
<ion-item>
  <ion-label slot="end">Checkbox Label</ion-label>
  <ion-checkbox></ion-checkbox>
</ion-item>

<!-- After -->
<ion-item>
  <ion-checkbox label-placement="end">Checkbox Label</ion-checkbox>
</ion-item>

<!-- Basic -->

<!-- Before -->
<ion-item>
  <ion-label>Checkbox Label</ion-label>
  <ion-checkbox></ion-checkbox>
</ion-item>

<!-- After -->
<ion-item>
  <ion-checkbox>Checkbox Label</ion-checkbox>
</ion-item>

<!-- Fixed Labels -->

<!-- Before -->
<ion-item>
  <ion-label position="fixed">Checkbox Label</ion-label>
  <ion-checkbox></ion-checkbox>
</ion-item>

<!-- After -->
<ion-item>
  <ion-checkbox labelPlacement="fixed">Checkbox Label</ion-checkbox>
</ion-item>

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

<!-- Before -->
<ion-item>
  <ion-label slot="end">Checkbox Label</ion-label>
  <ion-checkbox></ion-checkbox>
</ion-item>

<!-- After -->
<ion-item>
  <ion-checkbox labelPlacement="end">Checkbox Label</ion-checkbox>
</ion-item>

{/* Basic */}

{/* Before */}
<IonItem>
  <IonLabel>Checkbox Label</IonLabel>
  <IonCheckbox></IonCheckbox>
</IonItem>

{/* After */}
<IonItem>
  <IonCheckbox>Checkbox Label</IonCheckbox>
</IonItem>

{/* Fixed Labels */}

{/* Before */}
<IonItem>
  <IonLabel position="fixed">Checkbox Label</IonLabel>
  <IonCheckbox></IonCheckbox>
</IonItem>

{/* After */}
<IonItem>
  <IonCheckbox labelPlacement="fixed">Checkbox Label</IonCheckbox>
</IonItem>

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

{/* Before */}
<IonItem>
  <IonLabel slot="end">Checkbox Label</IonLabel>
  <IonCheckbox></IonCheckbox>
</IonItem>

{/* After */}
<IonItem>
  <IonCheckbox labelPlacement="end">Checkbox Label</IonCheckbox>
</IonItem>

<!-- Basic -->

<!-- Before -->
<ion-item>
  <ion-label>Checkbox Label</ion-label>
  <ion-checkbox></ion-checkbox>
</ion-item>

<!-- After -->
<ion-item>
  <ion-checkbox>Checkbox Label</ion-checkbox>
</ion-item>

<!-- Fixed Labels -->

<!-- Before -->
<ion-item>
  <ion-label position="fixed">Checkbox Label</ion-label>
  <ion-checkbox></ion-checkbox>
</ion-item>

<!-- After -->
<ion-item>
  <ion-checkbox label-placement="fixed">Checkbox Label</ion-checkbox>
</ion-item>

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

<!-- Before -->
<ion-item>
  <ion-label slot="end">Checkbox Label</ion-label>
  <ion-checkbox></ion-checkbox>
</ion-item>

<!-- After -->
<ion-item>
  <ion-checkbox label-placement="end">Checkbox Label</ion-checkbox>
</ion-item>

注意

在過去的 Ionic 版本中，ion-item 是 ion-checkbox 正確運作所必需的。從 Ionic 7.0 開始，只有當項目放置在 ion-list 中時，才應在 ion-item 中使用 ion-checkbox。此外，ion-item 不再是 ion-checkbox 正確運作所必需的。

使用舊版語法

Ionic 使用啟發法來偵測應用程式是否正在使用現代核取方塊語法。在某些情況下，最好繼續使用舊版語法。開發人員可以在 ion-checkbox 上將 legacy 屬性設定為 true，以強制該核取方塊實例使用舊版語法。

屬性

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`

已停用

描述	如果為 `true`，使用者將無法與核取方塊互動。
屬性	`已停用`
類型	`boolean`
預設	`false`

不確定

描述	如果為 `true`，核取方塊在視覺上將顯示為不確定狀態。
屬性	`不確定`
類型	`boolean`
預設	`false`

對齊

描述	如何在一行中排列標籤和核取方塊。`"start"`：標籤和核取方塊在 LTR 中會顯示在左側，在 RTL 中則會顯示在右側。`"end"`：標籤和核取方塊在 LTR 中會顯示在右側，在 RTL 中則會顯示在左側。`"space-between"`：標籤和核取方塊將顯示在該行的兩端，兩者之間有空間。設定此屬性會將核取方塊的 `display` 變更為 `block`。
屬性	`對齊`
類型	`"end" ｜ "space-between" ｜ "start" ｜ undefined`
預設	`undefined`

標籤位置

描述	標籤相對於核取方塊的位置。`"start"`：標籤在 LTR 中會顯示在核取方塊的左側，在 RTL 中則會顯示在右側。`"end"`：標籤在 LTR 中會顯示在核取方塊的右側，在 RTL 中則會顯示在左側。`"fixed"`：標籤的行為與 `"start"` 相同，只是它還具有固定的寬度。長文字將會被截斷並以省略符號（"..."）顯示。`"stacked"`：無論方向為何，標籤都會顯示在核取方塊的上方。標籤的對齊方式可以使用 `alignment` 屬性來控制。
屬性	`標籤位置`
類型	`"end" ｜ "fixed" ｜ "stacked" ｜ "start"`
預設	`'start'`

模式

描述	模式決定要使用的平台樣式。
屬性	`模式`
類型	`"ios" ｜ "md"`
預設	`undefined`

名稱

描述	控制項的名稱，會與表單資料一起提交。
屬性	`名稱`
類型	`字串`
預設	`this.inputId`

值

描述	核取方塊的值並不表示是否已勾選，請使用 `checked` 屬性來判斷是否已勾選。核取方塊的值類似於 `<input type="checkbox">` 的值，它只在核取方塊參與原生 `<form>` 時使用。
屬性	`值`
類型	`任何`
預設	`'on'`

事件

名稱	描述	冒泡
`ionBlur`	當核取方塊失去焦點時觸發。	`true`
`ionChange`	當 checked 屬性因使用者動作（例如點擊）而變更時觸發。當以程式方式設定 `checked` 屬性時，此事件不會觸發。	`true`
`ionFocus`	當核取方塊取得焦點時觸發。	`true`

方法

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

CSS Shadow Parts

名稱	描述
`容器`	核取方塊標記的容器。
`標籤`	描述核取方塊的標籤文字。
`標記`	用於指示已勾選狀態的核取記號。

CSS 自訂屬性

名稱	描述
`--border-color`	核取方塊圖示的邊框顏色
`--border-color-checked`	勾選時核取方塊圖示的邊框顏色
`--border-radius`	核取方塊圖示的邊框半徑
`--border-style`	核取方塊圖示的邊框樣式
`--border-width`	核取方塊圖示的邊框寬度
`--checkbox-background`	核取方塊圖示的背景
`--checkbox-background-checked`	勾選時核取方塊圖示的背景
`--checkmark-color`	勾選時核取方塊勾選記號的顏色
`--checkmark-width`	核取方塊勾選記號的筆劃寬度
`--size`	核取方塊圖示的大小
`--transition`	核取方塊圖示的過渡

名稱	描述
`--border-color`	核取方塊圖示的邊框顏色
`--border-color-checked`	勾選時核取方塊圖示的邊框顏色
`--border-radius`	核取方塊圖示的邊框半徑
`--border-style`	核取方塊圖示的邊框樣式
`--border-width`	核取方塊圖示的邊框寬度
`--checkbox-background`	核取方塊圖示的背景
`--checkbox-background-checked`	勾選時核取方塊圖示的背景
`--checkmark-color`	勾選時核取方塊勾選記號的顏色
`--checkmark-width`	核取方塊勾選記號的筆劃寬度
`--size`	核取方塊圖示的大小
`--transition`	核取方塊圖示的過渡

插槽

名稱	描述
``	要與核取方塊相關聯的標籤文字。使用 "labelPlacement" 屬性來控制標籤相對於核取方塊的位置。

基本用法​

標籤放置​

對齊​

對齊方式​

不確定狀態的核取方塊​

標籤內的連結​

主題​

CSS 自訂屬性​

介面​

CheckboxChangeEventDetail​

CheckboxCustomEvent​

從舊版核取方塊語法遷移​

使用現代語法​

使用舊版語法​

屬性​

alignment​

checked​

color​

已停用​

不確定​

對齊​

標籤位置​

模式​

名稱​

值​

事件​

方法​

CSS Shadow Parts​

CSS 自訂屬性​

插槽​

目錄

基本用法

標籤放置

對齊

對齊方式

不確定狀態的核取方塊

標籤內的連結

主題

CSS 自訂屬性

介面

CheckboxChangeEventDetail

CheckboxCustomEvent

從舊版核取方塊語法遷移

使用現代語法

使用舊版語法

屬性

alignment

checked

color

已停用

不確定

對齊

標籤位置

模式

名稱

值

事件

方法

CSS Shadow Parts

CSS 自訂屬性

插槽