ボタン グループ コンポーネント

React ボタン グループ コンポーネントは、IgrToggleButton を、水平 / 垂直配置、単一 / 複数選択、切り替えを備えたスタイル付きボタン グループに編成するために使用されます。

ライブ デモ

構造

React ボタン グループは、関連するトグル ボタンを共有コンテナーと個々のボタン アイテムを持つ単一グループに整理します。

React ボタン グループはトグル ボタンを含み、各ボタンにはアイコンとラベルを含めることができます。

Button Group
└── Toggle Button
    ├── Icon
    └── Label

作業の開始

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

前提条件とバージョン互換性

ターゲット フレームワークでサポートされているバージョンの Ignite UI for React パッケージを使用してください。フレームワーク パッケージ、ボタン グループ パッケージ、テーマ パッケージを同じリリース バージョンに保ってください。

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

npm install igniteui-react

次に、ボタン グループ ラッパーとそのテーマ CSS をインポートします。

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

IgrButtonGroup を使用する最もシンプルな方法は次のとおりです。

<IgrButtonGroup />

使用方法

IgrButtonGroup を使用して IgrToggleButton コンポーネントをラップします。デフォルトでボタンを選択するには、Selected 属性を使用します。

<IgrButtonGroup>
    <IgrToggleButton value="left">
        <IgrIcon name="format_align_left" collection="material"/>
        <IgrRipple/>
    </IgrToggleButton>
    <IgrToggleButton value="center">
        <IgrIcon name="format_align_center" collection="material"/>
        <IgrRipple/>
    </IgrToggleButton>
    <IgrToggleButton value="right">
        <IgrIcon name="format_align_right" collection="material"/>
        <IgrRipple/>
    </IgrToggleButton>
    <IgrToggleButton value="justify" selected={true}>
        <IgrIcon name="format_align_justify" collection="material"/>
        <IgrRipple/>
    </IgrToggleButton>
</IgrButtonGroup>

配置

ボタン グループは水平および垂直レイアウトをサポートします。Alignment プロパティを使用して、グループ内のボタンの方向を設定します。

選択

Ignite UI for React IgrButtonGroup の選択を構成するには、プラットフォーム固有の選択プロパティを使用します。Angular の場合は selectionMode、React、Web Components、Blazor の場合は selection を使用します。使用可能なモードは次のとおりです。

• single - ボタン グループのデフォルトの選択モードです。ユーザーは単一のボタンを選択/選択解除できます。
• single-required - ラジオ グループの動作を模倣します。選択できるボタンは 1 つだけで、最初に選択すると、ユーザーの操作によって選択解除することはできません。
• multiple - グループ内の複数のボタンを選択または選択解除できます。

以下のサンプルは、公開された IgrButtonGroup 選択モードを示しています。

IgrToggleButton は、Selected 属性または IgrButtonGroup の SelectedItems 属性を通じて選択済みとしてマークできます。

<IgrButtonGroup selectedItems={['bold']}>
    <IgrToggleButton value="bold">
        <IgrIcon name="bold" collection="material" />
        <IgrRipple />
    </IgrToggleButton>
    <IgrToggleButton value="italic">
        <IgrIcon name="italic" collection="material" />
        <IgrRipple />
    </IgrToggleButton>
    <IgrToggleButton value="underlined">
        <IgrIcon name="underlined" collection="material" />
        <IgrRipple />
    </IgrToggleButton>
</IgrButtonGroup>

状態

グループ内の各ボタンは、有効および無効のバリアントをサポートし、選択済みまたは未選択の状態にできます。含まれる IgrToggleButton コンポーネントが提供する状態動作を使用します。

インタラクション状態

グループ内の有効なボタンは、アイドル、ホバー、フォーカスのインタラクション状態をサポートします。含まれる IgrToggleButton コンポーネントが提供する状態動作を使用します。

レイアウト テンプレート

各ボタンにはテキスト、アイコン、またはその両方を使用できます。グループ全体でコンテンツ スタイルを統一し、ボタン コンテンツ API を使用して各ボタンに表示するアイコンとラベルを制御します。

カスタム トグル ボタン

React の場合は、個々のトグル ボタンを使用してカスタム ボタン グループを作成します。各ボタンには独自の値、アイコン、ラベル、選択状態、無効状態を定義できます。

ボタン グループ、トグル ボタン、アイコン コンポーネントをインポートします。

import { IgrButtonGroup, IgrToggleButton, IgrIcon } from 'igniteui-react';

次に、JSX でカスタム ボタンを定義します。

<IgrButtonGroup>
    <IgrToggleButton value="align-left">
        <IgrIcon name="format_align_left" collection="material" />
    </IgrToggleButton>
    <IgrToggleButton value="align-center" selected={true}>
        <IgrIcon name="format_align_center" collection="material" />
    </IgrToggleButton>
    <IgrToggleButton value="align-right" disabled={true}>
        <IgrIcon name="format_align_right" collection="material" />
    </IgrToggleButton>
</IgrButtonGroup>

サイズ

--ig-size CSS カスタム プロパティを使用して、ボタン グループのサイズを制御できます。

<IgrButtonGroup style={{ '--ig-size': 'var(--ig-size-small)' } as React.CSSProperties}>
</IgrButtonGroup>

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

使用する場合: ユーザーが 1 つまたは複数のオプションを選択できる関連するトグル アクションを整理するためにボタン グループを使用します。

使用しない場合: 関連のないアクションや単一のトグル アクションにはボタン グループを使用しないでください。代わりにスタンドアロンの IgrToggleButton を使用します。

Do	Don’t

プロパティ

ボタン グループのプロパティはコンポーネント API リファレンスから生成されます。

プロパティの行は、ドキュメントのビルド時に型付き API ソースから注入されます。

スタイル設定

React ボタン グループは CSS パーツを使用して、グループ コンテナーと個々のトグル ボタンをスタイル設定します。ボタン グループの group パーツとトグル ボタンの toggle パーツを使用して外観をカスタマイズします。

Sass テーマ

Ignite UI for React テーマ システムを使用して、アプリケーションの他の部分と一貫したスタイルでボタン グループをカスタマイズします。

カスタム ボタン グループ テーマを作成する前にテーマ関数をインポートします。

@use "igniteui-theming" as *;

button-group-theme でテーマを作成し、グローバル スタイルシートに含めます。$item-background パラメーターは関連するインタラクション状態の色のベースとして使用されます。ボタン グループの外観をより細かく制御する必要がある場合は、追加のパラメーターをオーバーライドします。

$custom-button-group: button-group-theme(
    $item-background: #57a5cd,
);

igc-button-group {
    @include button-group($custom-button-group);
}

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

CSS 変数

次の CSS 変数を使用して、ボタン グループ アイテムの色とインタラクション状態をカスタマイズします。ボタン グループ要素に設定すると、含まれるトグル ボタンにスタイルが適用されます。

スタイル パーツ

ボタン グループとそれに含まれるトグル ボタンをターゲットにするには、次の CSS パーツを使用します。

カスタム スタイル設定

次の例では、グループの背景とパディングを変更し、含まれるトグル ボタンのテキスト色を変更します。

igc-button-group::part(group) {
  background-color: var(--ig-primary-500);
  padding: 8px;
}

igc-toggle-button::part(toggle) {
  color: var(--ig-secondary-300);
}

Tailwind によるスタイル設定

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

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

<IgrButtonGroup className="!light-button-group ![--item-background:#7B9E89]"></IgrButtonGroup>

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

アクセシビリティ

React Button Group は、関連するトグル ボタンを整理しながら、各ボタンの選択状態と無効状態を公開します。

キーボード インタラクション

ボタン グループは、内包するトグル ボタンにキーボード インタラクションを委譲します。各トグル ボタンはネイティブ ボタンをレンダリングするため、標準のボタン キーボード動作によってフォーカスされたアイテムがアクティブ化され、設定された選択モードに従って選択状態が更新されます。

ボタン グループが無効の場合、内包するトグル ボタンも無効になり、キーボードによるインタラクティブ操作に対応しなくなります。

スクリーン リーダー / ARIA

ボタン グループはグループの関係を公開し、各トグル ボタンはネイティブ ボタン セマンティクスを通じてその状態を公開します。

• グループ コンテナーは role="group" を使用し、aria-disabled を通じてグループの無効状態を反映します。
• 各トグル ボタンは、選択状態に aria-pressed、無効状態に aria-disabled を持つネイティブ button をレンダリングします。
• グループはユーザーの操作によりトグル ボタンの選択状態が変化した後、igcSelect および igcDeselect を発行します。イベントの詳細はトグル ボタンの value です。
• すべてのトグル ボタンに表示テキストまたは aria-label を提供してください。特にアイコンのみのコントロールでは重要です。

アクセシビリティ準拠

インフラジスティックスは、アクセシビリティ準拠 トピックで、Section 508 および WCAG 2.1 ガイドライン領域における Ignite UI for React のアクセシビリティ サポートを文書化しています。

ユーザー側の責任:

• 各トグル ボタンに明確な表示ラベルまたはアクセシブルな名前を付けてください。特にアイコンのみのボタンでは重要です。
• グループの選択モードをコントロールの目的に合わせて設定し、ユーザーが 1 つまたは複数のオプションを選択できるかどうかを理解できるようにしてください。
• グループまたはその選択状態をカスタマイズする際は、論理的なボタンの順序と十分な色のコントラストを維持してください。

トラブルシューティング

React ボタン グループのトラブルシューティング ガイダンスは、一般的な選択の問題に対して問題、原因、修正のフォーマットで提供されます。

selectedItems でボタンが選択されないのはなぜですか?

すべてのトグル ボタンに一意の value 属性があることを確認してください。selectedItems プロパティはこれらの値に依存します。

既知の制限

React ボタン グループはトグル ボタンを調整しますが、個々のラベルやアクセシブルな名前を置き換えるものではありません。

• 選択動作は設定された selection モードに依存します。
• selectedItems プロパティは、含まれるトグル ボタンの一意の value 属性に依存します。
• ボタン グループはボタンのラベルやアイコンを提供しません。各トグル ボタンのコンテンツは個別に定義してください。

API リファレンス

React ボタン グループ API リファレンスは、コンポーネントと関連するトグル ボタン機能の完全な API サーフェスを提供します。

依存関係

React ボタン グループは、プラットフォーム パッケージとそのテーマ スタイルシートが必要です。サンプルではトグル ボタン、アイコン、リップル コンポーネントも使用します。

その他のリソース

API の詳細とプロジェクト サポートについては、次の React リソースを使用してください。

• Ignite UI for React フォーラム (英語)
• Ignite UI for React GitHub (英語)

関連コンポーネント

React ボタン グループは選択可能なトグル ボタンで構成されています。グループではなく個別のトグル アクションが必要な場合は、次の関連コンポーネントを使用してください。

• IgrToggleButton

FAQ

これらのよくある質問は、React ボタン グループの選択、コンテンツ、設定に関する一般的なシナリオをカバーします。