Switch コンポーネント

Ignite UI for React Switch コンポーネントは、iOS のスイッチ コンポーネントと同様に動作するバイナリ選択の選択コンポーネントです。

ライブ デモ

構造

React Switch には、バイナリ状態を変更するコントロールと、オプションのラベルが含まれています。

以下の図は、React Switch の論理構造を示しています。コントロールはバイナリ状態を管理し、オプションのラベルはスイッチによって制御される設定を説明します。

Switch
├── Control
└── Label (optional)

作業の開始

React Switch を使用するには、基本的なプロジェクト設定について Ignite UI for React の作業の開始 トピックに従ってから、ターゲット プラットフォーム用にコンポーネントを登録します。

IgrSwitch コンポーネントにより、オン/オフ状態を切り替えることができます。デフォルトのスタイル設定はマテリアル デザイン ガイドラインの選択コントロールの仕様に基づきます。

igniteui-react パッケージを使用する React では、パッケージをインストールします。

npm install igniteui-react

次に、Switch ラッパーとそのテーマ CSS をインポートします。

import { IgrSwitch } from 'igniteui-react';
import 'igniteui-webcomponents/themes/light/bootstrap.css';

IgrSwitch の使用を開始する最も簡単な方法は次のとおりです。

<IgrSwitch></IgrSwitch>

使用方法

React Switch は、ユーザーが状態を変更するとすぐに反映される設定用のバイナリ選択コントロールとして使用します。

以下の例は、基本的な Switch の構成を示しています。スイッチに意味のあるラベルを付けるには、開始タグと終了タグの間にテキストを配置するだけです。

<IgrSwitch>Accept terms</IgrSwitch>

required プロパティを使用して、スイッチを必須としてマークできます。

<IgrSwitch required={true}></IgrSwitch>

invalid プロパティを使用して、スイッチを無効としてマークできます。

<IgrSwitch invalid={true}></IgrSwitch>

インタラクション状態

Switch は Enabled または Disabled 状態で挿入できます。Enabled 状態では、スイッチは Hover、Focused、および Focused & Hover の状態もサポートします。

無効状態

スイッチの状態を Disabled に設定して、ユーザーの操作を許可しないようにすることもできます。この状態を設定するには、disabled 属性を使用できます。

<IgrSwitch disabled={true}></IgrSwitch>

オン/オフ状態

Switch は On または Off の状態に設定して、設定が有効か無効かを示すことができます。

<IgrSwitch checked={true}>On</IgrSwitch>
<IgrSwitch checked={false}>Off</IgrSwitch>

レイアウト

スイッチの LabelPosition プロパティを設定することにより、スイッチの切り替えの前または後にラベルを配置するかどうかを指定できます。許可される値は、before と after (デフォルト) です。

<IgrSwitch aria-labelledby="switch-label" labelPosition="before"><span id="switch-label">Label</span></IgrSwitch>

スイッチには、スイッチの外部の要素でラベルを付けることもできます。この場合、ユーザーはニーズに応じてラベルの位置とスタイルを完全に制御できます。

<>
  <span id="switch-label">Label</span>
  <IgrSwitch aria-labelledby="switch-label"></IgrSwitch>
</>

使用すべき場合と使用すべきでない場合

使用する場合: ユーザーが変更するとすぐに反映されるオン/オフの設定には Switch を使用します。

使用しない場合: ユーザーが後でフォームを送信するために 1 つ以上のオプションを選択する場合は Checkbox を使用し、コントロールがアクションまたは切り替え可能なコマンドを表す場合は Button を使用します。

Do	Don’t

プロパティ

スタイル設定

React Switch は、CSS パーツと CSS 変数を使用して、トラック、つまみ、およびラベルのスタイルを設定します。

Sass テーマ設定

Ignite UI for React テーマ システムを使用して、アプリケーションの他の部分と一貫性のある Switch のスタイルを設定します。

カスタム Switch テーマを作成する前に、テーマ関数をインポートします。

@use "igniteui-theming" as *;

switch-theme を使用してテーマを作成し、それをグローバル スタイルシートに含めます。トラックとつまみのパラメーターは、関連するインタラクション状態の色のベースとして使用されます。

$custom-switch: switch-theme(
    $track-on-color: #57a5cd,
);

igc-switch {
    @include switch($custom-switch);
}

同じテーマが Web Components に直接適用され、React および Blazor ラッパーによってレンダリングされる基になる igc-switch 要素にも適用されます。

CSS 変数

以下の CSS 変数を使用して、Switch の色とインタラクション状態をカスタマイズします。これらを Switch 要素に設定して、そのトラック、つまみ、およびラベルにスタイルを適用します。

スタイル パーツ

以下の CSS パーツを使用して、Switch とその内部要素をターゲットにします。

カスタム スタイル設定

以下の例は、チェック済みおよびチェック解除の状態のトラックとつまみの色を変更します。

igc-switch {
  --thumb-on-color: white;
  --thumb-off-color: var(--ig-success-500);
  --track-on-color: var(--ig-success-500); /* Background color when checked */
  --track-off-color: white; /* Background color when unchecked */
  --track-on-hover-color: var(--ig-success-500); /* Background hover color when checked */
}

Tailwind でのスタイル設定

igniteui-theming のカスタム Tailwind ユーティリティ クラスを使用して React Switch のスタイルを設定できます。まず Tailwind をセットアップ してから、グローバル スタイルシートに Ignite UI ユーティリティをインポートします。

@import "tailwindcss";
@import "igniteui-theming/tailwind/utilities/material.css";

<IgrSwitch className="!light-switch ![--track-on-color:#7B9E89]"></IgrSwitch>

感嘆符 (!) は、Switch のデフォルトのテーマ スタイルよりも Tailwind ユーティリティを優先させます。

アクセシビリティ

React Switch はバイナリ状態を公開し、そのラベルまたは ARIA 属性を通じてアクセシブルな名前をサポートします。

キーボード操作

スクリーン リーダー/ARIA

Switch は、バイナリのチェック状態を持つインタラクティブなコントロールをレンダリングします。表示されるラベル コンテンツ、または aria-label や aria-labelledby によるアクセシブルな名前を用意し、ラベルはスイッチが制御する設定に固有のものにしてください。

• コントロールは、そのチェック状態と無効状態を支援技術に公開します。
• チェック状態が変更されると、igcChange イベントが発生します。

アクセシビリティ コンプライアンス

Infragistics は、Section 508 および WCAG 2.1 ガイドライン領域に対する Ignite UI for React のアクセシビリティ サポートを アクセシビリティ コンプライアンス トピックで説明しています。

トラブルシューティング

このセクションを使用して、Switch をフォーム フィールド、インタラクティブなコマンド、または設定コントロールとして扱う前に、境界と一般的な決定事項を確認してください。

Switch がフォームで送信されないのはなぜですか?

Switch はフォームに関連付けられますが、フォームが送信されたときに値を提供するには name と value が必要です。両方のプロパティを設定し、対象プラットフォームでサポートされているフォーム統合を使用してください。

スクリーン リーダーで Switch が正しく読み上げられないのはなぜですか?

Switch にはアクセシブルな名前が必要です。表示されるラベル コンテンツを追加するか、aria-labelledby で外部ラベルを参照してください。表示テキストが利用できない場合は aria-label を使用してください。

既知の制限事項

React Switch には、プラットフォームに依存しない以下の制限事項があります。

• Switch は 1 つのバイナリ設定を表します。ユーザーが複数の選択肢または後から行うフォーム選択を必要とする場合は、別のコントロールを使用してください。
• Switch にラベルまたは ARIA 命名属性がない場合、アクセシブルな名前は自動的には提供されません。

API リファレンス

React Switch の完全な API リファレンスを参照してください。

依存関係

React Switch は、視覚的なスタイルを適用するためにテーマ スタイルシートを必要とします。フレームワーク固有のセットアップについては、作業の開始 を参照してください。

その他のリソース

API の詳細、例、およびプロジェクトのサポートについては、以下の React リソースを使用してください。

• Lists - Design System Pattern
• Ignite UI for React フォーラム (英語)
• Ignite UI for React GitHub (英語)

関連コンポーネント

• Checkbox - ユーザーが 1 つ以上のオプションを選択する場合、特にフォームの一部として使用する場合は Checkbox を使用します。

• Button - コントロールが設定ではなくコマンドまたはアクションを表す場合は Button を使用します。

FAQ