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

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

ライブ デモ

構造

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

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

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

作業の開始

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

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

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

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

npm install igniteui-webcomponents

次に、ButtonGroup とそのテーマ CSS をインポートし、コンポーネントを登録します。

import { defineComponents, IgcButtonGroupComponent } from "igniteui-webcomponents";
import 'igniteui-webcomponents/themes/light/bootstrap.css';

defineComponents(IgcButtonGroupComponent);

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

<igc-button-group></igc-button-group>

使用方法

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

 <igc-button-group>
    <igc-toggle-button value="left">
        <igc-icon name="format_align_left" collection="material"></igc-icon>
        <igc-ripple></igc-ripple>
    </igc-toggle-button>

    <igc-toggle-button value="center">
        <igc-icon name="format_align_center" collection="material"></igc-icon>
        <igc-ripple></igc-ripple>
    </igc-toggle-button>

    <igc-toggle-button value="right">
        <igc-icon name="format_align_right" collection="material"></igc-icon>
        <igc-ripple></igc-ripple>
    </igc-toggle-button>

    <igc-toggle-button value="justify" selected>
        <igc-icon name="format_align_justify" collection="material"></igc-icon>
        <igc-ripple></igc-ripple>
    </igc-toggle-button>
</igc-button-group>

配置

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

選択

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

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

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

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

<igc-button-group selected-items='["bold"]'>
    <igc-toggle-button value="bold">
        <igc-icon name="bold" collection="material"></igc-icon>
        <igc-ripple></igc-ripple>
    </igc-toggle-button>

    <igc-toggle-button value="italic">
        <igc-icon name="italic" collection="material"></igc-icon>
        <igc-ripple></igc-ripple>
    </igc-toggle-button>

    <igc-toggle-button value="underlined">
        <igc-icon name="underlined" collection="material"></igc-icon>
        <igc-ripple></igc-ripple>
    </igc-toggle-button>
</igc-button-group>

状態

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

インタラクション状態

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

レイアウト テンプレート

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

カスタム トグル ボタン

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

ボタン グループとトグル ボタン コンポーネントを登録します。

import { defineComponents, IgcButtonGroupComponent, IgcToggleButtonComponent, IgcIconComponent } from 'igniteui-webcomponents';

defineComponents(IgcButtonGroupComponent, IgcToggleButtonComponent, IgcIconComponent);

次に、マークアップでカスタム ボタンを定義します。

<igc-button-group>
    <igc-toggle-button value="align-left">
        <igc-icon name="format_align_left" collection="material"></igc-icon>
    </igc-toggle-button>
    <igc-toggle-button value="align-center" selected>
        <igc-icon name="format_align_center" collection="material"></igc-icon>
    </igc-toggle-button>
    <igc-toggle-button value="align-right" disabled>
        <igc-icon name="format_align_right" collection="material"></igc-icon>
    </igc-toggle-button>
</igc-button-group>

サイズ

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

<igc-button-group style="--ig-size: var(--ig-size-small)"></igc-button-group>

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

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

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

Do	Don’t

プロパティ

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

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

スタイル設定

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

Sass テーマ

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

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

@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 ユーティリティ クラスを使用して Web Components ボタン グループをスタイル設定できます。最初に Tailwind を設定 してから、グローバル スタイルシートに Ignite UI ユーティリティをインポートします。

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

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

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

アクセシビリティ

Web Components 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 Web Components のアクセシビリティ サポートを文書化しています。

ユーザー側の責任:

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

トラブルシューティング

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

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

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

既知の制限

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

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

API リファレンス

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

依存関係

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

その他のリソース

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

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

関連コンポーネント

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

• ToggleButton

FAQ

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