バージョン: v8

ion-toggle

シャドウ

トグルは、単一オプションの状態を変更するスイッチです。押したりスワイプしたりすることで、オンまたはオフに切り替えることができます。 `checked` プロパティを設定することで、プログラムでトグルをチェックすることもできます。

基本的な使い方

オン/オフラベル

トグルは、`enableOnOffLabels` プロパティを設定することで、オン/オフラベルを有効にできます。これは、オンとオフのトグルを区別しやすくするため、アクセシビリティにとって重要です。

リスト内のトグル

トグルは、アイテムコンポーネントとリストコンポーネントを使用することで、リストビューでも使用できます。

ラベルの配置

開発者は、`labelPlacement` プロパティを使用して、コントロールに対するラベルの配置方法を制御できます。

配置

開発者は、 `alignment` プロパティを使用して、ラベルとコントロールがクロス軸上でどのように配置されるかを制御できます。このプロパティは、flexboxの `align-items` プロパティを反映しています。

注記

スタックされたトグルは、`alignment` プロパティを使用して配置できます。これは、ラベルとコントロールを水平方向に中央揃えする必要がある場合に役立ちます。

均等配置

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

テーマ設定

色

CSSカスタムプロパティ

CSSカスタムプロパティは、標準CSSと組み合わせて、トグルのさまざまな部分をターゲットにすることができます。 `--handle-width` および `--handle-height` カスタムプロパティを使用してハンドルサイズをカスタマイズしながら、トグルの `width` と `height` を直接変更して、トラックのサイズを変更できます。

CSSシャドウパーツ

公開されている特定のシャドウパーツをターゲットにすることで、トグルをさらにカスタマイズできます。これらのパーツのCSSプロパティはすべてスタイル設定でき、CSSカスタムプロパティと組み合わせることもできます。

レガシートグル構文からの移行

Ionic 7.0では、よりシンプルなトグル構文が導入されました。この新しい構文により、トグルの設定に必要な定型コードが削減され、アクセシビリティの問題が解決され、開発エクスペリエンスが向上します。

開発者はレガシー構文を引き続き使用できますが、できるだけ早く移行することをお勧めします。

最新構文の使用

最新構文を使用するには、`ion-label` を削除し、`ion-toggle` 内にラベルを直接渡します。ラベルの配置は、`ion-toggle` の `labelPlacement` プロパティを使用して設定できます。ラベルとコントロールが行に配置される方法は、`ion-toggle` の `justify` プロパティを使用して制御できます。

JavaScript
Angular
React
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>

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

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

<!-- 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-toggle` が正しく機能するには `ion-item` が必要でした。Ionic 7.0以降、`ion-toggle` は、アイテムが `ion-list` に配置されている場合にのみ `ion-item` 内で使用してください。また、`ion-toggle` が正しく機能するために `ion-item` は不要になりました。

レガシー構文の使用

Ionicは、アプリが最新トグル構文を使用しているかどうかを検出するためのヒューリスティックを使用します。場合によっては、レガシー構文を引き続き使用することをお勧めします。開発者は、`ion-toggle` の `legacy` プロパティを `true` に設定して、そのトグルのインスタンスにレガシー構文を強制的に使用させることができます。

インターフェース

ToggleChangeEventDetail

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

ToggleCustomEvent

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

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"`：ラベルとトグルは行の両端に表示され、2つの要素の間にスペースが空きます。このプロパティを設定すると、トグルの`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は、使用するプラットフォームスタイルを決定します。
属性	`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シャドウパーツ

名前	説明
`handle`	チェック状態を変更するために使用されるトグルハンドル、またはノブ。
`label`	トグルを説明するラベルテキスト。
`track`	トグルの背景トラック。

CSSカスタムプロパティ

名前	説明
`--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`	チェックされたときのトグルトラックの背景

名前	説明
`--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"プロパティを使用して、トグルに対するラベルの配置場所を制御します。

基本的な使い方​

オン/オフラベル​

リスト内のトグル​

ラベルの配置​

配置​

均等配置​

テーマ設定​

色​

CSSカスタムプロパティ​

CSSシャドウパーツ​

レガシートグル構文からの移行​

最新構文の使用​

レガシー構文の使用​

インターフェース​

ToggleChangeEventDetail​

ToggleCustomEvent​

プロパティ​

alignment​

checked​

color​

disabled​

enableOnOffLabels​

justify​

labelPlacement​

mode​

name​

value​

イベント​

メソッド​

CSSシャドウパーツ​

CSSカスタムプロパティ​

スロット​

目次

基本的な使い方

オン/オフラベル

リスト内のトグル

ラベルの配置

配置

均等配置

テーマ設定

色

CSSカスタムプロパティ

CSSシャドウパーツ

レガシートグル構文からの移行

最新構文の使用

レガシー構文の使用

インターフェース

ToggleChangeEventDetail

ToggleCustomEvent

プロパティ

alignment

checked

color

disabled

enableOnOffLabels

justify

labelPlacement

mode

name

value

イベント

メソッド

CSSシャドウパーツ

CSSカスタムプロパティ

スロット