ion-checkbox

shadow

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

基本的な使い方

Label Placement

開発者は labelPlacement プロパティを使用して、ラベルがどのように配置されるかを制御することができます。

Justification

開発者は justify プロパティを使用して、ラベルとコントロールの行の詰め方を制御することができます。

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

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

Angular

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

React

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

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>

note

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

レガシーな構文の使い方

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

プロパティ

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 & Record<never, never> ｜ 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"と同じ動作になります。長いテキストは省略記号("...")で切り捨てられます。
Attribute	label-placement
Type	"end" ｜ "fixed" ｜ "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"プロパティを使用して、チェックボックスに対するラベルの配置を制御します。