Version: v7

ion-checkbox

Checkboxを使用すると、一連のオプションから複数のオプションを選択できます。選択すると、チェックマークが付いた状態(checked)で表示されます。checkboxをクリックすると、 checked プロパティーが切り替わります。checked プロパティを設定して、プログラムで checked を切り替えることもできます。

基本的な使い方

Label Placement

開発者は labelPlacement プロパティを使用して、ラベルをコントロールに対してどのように配置するかを制御できます。このプロパティはフレックスボックスの flex-direction プロパティを反映しています。

Alignment

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

Stacked checkboxes can be aligned using the alignment property. This can be useful when the label and control need to be centered horizontally.

Justification

開発者は justify プロパティを使用して、ラベルとコントロールの行の詰め方を制御することができます。このプロパティはフレックスボックスの justify-content プロパティを反映しています。

note

ion-itemは、 justify がどのように機能するかを強調するためにデモで使用されているだけです。 justify が正しく機能するために必須ではありません。

Indeterminate Checkboxes

テーマ

CSSカスタムプロパティ

Interfaces

CheckboxChangeEventDetail

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

CheckboxCustomEvent

必須ではありませんが、このコンポーネントから発行される Ionic イベントでより強く型付けを行うために、CustomEvent インターフェースの代わりにこのインターフェースを使用することが可能です。

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

レガシーなチェックボックス構文からのマイグレーション

Ionic 7.0では、よりシンプルなチェックボックス構文が導入されました。この新しい構文は、チェックボックスの設定に必要な定型文を減らし、アクセシビリティの問題を解決し、開発者のエクスペリエンスを向上させます。

開発者は、この移行を一度に1つのチェックボックスずつ実行することができます。開発者はレガシー構文を使い続けることができますが、できるだけ早く移行することをお勧めします。

最新の構文の使い方

最新の構文を使用するには、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>

note

Ionic の過去のバージョンでは、ion-checkbox が正しく機能するために ion-item が必要でした。Ionic 7.0 からは、ion-checkbox は ion-item の中で、そのアイテムが ion-list に配置される場合にのみ使用されます。また、ion-checkboxが正しく機能するためには、ion-itemはもはや必須ではありません。

レガシーな構文の使い方

Ionicは、アプリが最新のチェックボックス構文を使用しているかどうかをヒューリスティックに検出します。場合によっては、レガシーな構文を使い続けることが望ましい場合もあります。開発者は ion-checkbox の legacy プロパティを true に設定することで、そのチェックボックスのインスタンスがレガシー構文を使用するように強制できます。

プロパティ

alignment

Description	横軸上のチェックボックスとラベルの配置を制御する方法。start"`：ラベルとコントロールはLTRでは横軸の左側に、RTLでは右側に表示されます。center"`：ラベルとコントロールはLTRでもRTLでも十字軸の中央に表示されます。
Attribute	`alignment`
Type	`"center" ｜ "start"`
Default	`'center'`

checked

Description	`true`の場合、チェックボックスが選択される。
Attribute	`checked`
Type	`boolean`
Default	`false`

color

Description	アプリケーションのカラーパレットから使用する色を指定します。デフォルトのオプションは以下の通りです。 `"primary"`, `"secondary"`, `"tertiary"`, `"success"`, `"warning"`, `"danger"`, `"light"`, `"medium"`, と `"dark"` です．色に関する詳しい情報は theming を参照してください。
Attribute	`color`
Type	`"danger" ｜ "dark" ｜ "light" ｜ "medium" ｜ "primary" ｜ "secondary" ｜ "success" ｜ "tertiary" ｜ "warning" ｜ string ｜ undefined`
Default	`undefined`

disabled

Description	`true`の場合、ユーザはチェックボックスと対話することができません。
Attribute	`disabled`
Type	`boolean`
Default	`false`

indeterminate

Description	`true`の場合、チェックボックスは視覚的に不定形と表示されます。
Attribute	`indeterminate`
Type	`boolean`
Default	`false`

justify

Description	ラベルとチェックボックスを1行にまとめる方法。`"start"`：ラベルとチェックボックスは、LTRでは左に、RTLでは右に表示されます。`"end"`：ラベルとチェックボックスは、LTRでは右に、RTLでは左に表示されます。`"space-between"`：ラベルとチェックボックスは、2つの要素の間にスペースがある状態で、行の反対側の端に表示されます。
Attribute	`justify`
Type	`"end" ｜ "space-between" ｜ "start"`
Default	`'space-between'`

labelPlacement

Description	チェックボックスに対するラベルの位置。start"`：ラベルはLTRではチェックボックスの左に、RTLでは右に表示されます。end"`：ラベルはLTRではチェックボックスの右、RTLでは左に表示されます。fixed"`：ラベルの幅が固定される以外は` "start" `と同じ動作をします。長いテキストは省略記号("...")で切り捨てられます。積み重ね"`：ラベルは向きに関係なくチェックボックスの上に表示されます。ラベルの整列は `alignment` プロパティで制御できます。
Attribute	`label-placement`
Type	`"end" ｜ "fixed" ｜ "stacked" ｜ "start"`
Default	`'start'`

legacy

Description	`legacy`プロパティを`true`に設定すると、強制的にレガシーフォームコントロールのマークアップを使用することができます。Ionicは、チェックボックスが`aria-label`属性を使用しているか、デフォルトスロットにテキストがある場合にのみ、モダンなフォームマークアップを選択します。そのため、`legacy`プロパティは、この自動オプトイン動作を回避したい場合にのみ、エスケープハッチとして使用する必要があります。なお、このプロパティはIonicの今後のメジャーリリースで削除され、すべてのフォームコンポーネントは最新のフォームマークアップを使用するようオプトインされる予定です。
Attribute	`legacy`
Type	`boolean ｜ undefined`
Default	`undefined`

mode

Description	modeは、どのプラットフォームのスタイルを使用するかを決定します。
Attribute	`mode`
Type	`"ios" ｜ "md"`
Default	`undefined`

name

Description	フォームデータとともに送信されるコントロールの名前。
Attribute	`name`
Type	`string`
Default	`this.inputId`

value

Description	チェックボックスの値は、チェックされているかどうかを意味するものではなく、`checked`プロパティを使用します。チェックボックスの値は `<input type="checkbox">` の値に似ており、チェックボックスがネイティブの `<form>` に参加する場合にのみ使用されます。
Attribute	`value`
Type	`any`
Default	`'on'`

イベント

Name	Description
`ionBlur`	チェックボックスのフォーカスが外れたときに発行されます。
`ionChange`	クリックなどのユーザー操作によりcheckedプロパティが変更された場合に発生します。プログラムによってcheckedプロパティを設定した場合は、このイベントは発生しません。
`ionFocus`	チェックボックスにフォーカスが当たったときに発行されます。

メソッド

No public methods available for this component.

CSS Shadow Parts

Name	Description
`container`	チェックボックスマークのコンテナです。
`mark`	チェックされた状態を示すために使用されるチェックマークです。

CSSカスタムプロパティ

Name	Description
`--border-color`	チェックボックスアイコンのボーダーカラー
`--border-color-checked`	チェックボックスのアイコンがチェックされたときのボーダーカラー
`--border-radius`	チェックボックスアイコンの境界半径
`--border-style`	チェックボックスアイコンのボーダースタイル
`--border-width`	チェックボックスアイコンのボーダー幅
`--checkbox-background`	チェックボックスアイコンの背景
`--checkbox-background-checked`	チェックしたときのチェックボックスアイコンの背景
`--checkmark-color`	チェックボックスのチェックマークがチェックされたときの色
`--checkmark-width`	チェックボックス・チェックマークのストローク幅
`--size`	チェックボックスのアイコンの大きさ
`--transition`	チェックボックスアイコンの遷移

Slots

Name	Description
``	チェックボックスと関連付けるラベルテキスト。"labelPlacement"プロパティを使用して、チェックボックスに対するラベルの配置を制御します。

基本的な使い方​

Label Placement​

Alignment​

note

Justification​

note

Indeterminate Checkboxes​

テーマ​

CSSカスタムプロパティ​

Interfaces​

CheckboxChangeEventDetail​

CheckboxCustomEvent​

レガシーなチェックボックス構文からのマイグレーション​

最新の構文の使い方​

note

レガシーな構文の使い方​

プロパティ​

alignment​

checked​

color​

disabled​

indeterminate​

justify​

labelPlacement​

legacy​

mode​

name​

value​

イベント​

メソッド​

CSS Shadow Parts​

CSSカスタムプロパティ​

Slots​

Contents

基本的な使い方

Label Placement

Alignment

Justification

Indeterminate Checkboxes

テーマ

CSSカスタムプロパティ

Interfaces

CheckboxChangeEventDetail

CheckboxCustomEvent

レガシーなチェックボックス構文からのマイグレーション

最新の構文の使い方

レガシーな構文の使い方

プロパティ

alignment

checked

color

disabled

indeterminate

justify

labelPlacement

legacy

mode

name

value

イベント

メソッド

CSS Shadow Parts

CSSカスタムプロパティ

Slots