Angular ComboBox (コンボボックス) コンポーネントの概要

Angular ComboBox コンポーネントは、入力可能なドロップダウン リストを表し、ユーザーが事前定義されたリストから複数のオプションを選択できるようにします。Ignite UI for Angular ComboBox コンポーネントは、フィルタリング機能、グループ化、ドロップダウン リストへのカスタム値の追加などの機能も提供します。HTML select タグの代わりに使用でき、データ バインディング (ローカルおよびリモート)、フィルタリング、グループ化、項目、ヘッダー、フッターのカスタム テンプレート、カスタム値など、すぐに使用できる機能がいくつかあります。

Angular ComboBox の例

この Angular ComboBox の例では、ユーザーが項目をフィルターし、提供されたデータを使用して選択を実行する方法を確認できます。さらに、ComboBox は、キーボード ナビゲーションとカスタム スタイル設定機能を公開します。

Angular ComboBox 機能

コンボボックス コントロールは以下の機能を公開します。

• ローカル データおよびリモート データへのバインド
• 値バインディング
• フィルタリング
• グループ化
• カスタム値
• テンプレート
• テンプレート駆動フォームおよびリアクティブ フォームとの統合

Ignite UI for Angular ComboBox を使用した作業の開始

Ignite UI for Angular ComboBox コンポーネントを使用した作業を開始するには、Ignite UI for Angular をインストールする必要があります。既存の Angular アプリケーションで、以下のコマンドを入力します。

ng add igniteui-angular

Ignite UI for Angular については、「はじめに」トピックをご覧ください。

次に、app.module.ts ファイルに IgxComboModule をインポートします。

import { IgxComboModule } from 'igniteui-angular/combo';
// import { IgxComboModule } from '@infragistics/igniteui-angular'; for licensed package

@NgModule({
    imports: [
        ...
        IgxComboModule,
        ...
    ]
})
export class AppModule {}

あるいは、16.0.0 以降、IgxComboComponent をスタンドアロンの依存関係としてインポートすることも、IGX_COMBO_DIRECTIVES トークンを使用してコンポーネントとそのすべてのサポート コンポーネントおよびディレクティブをインポートすることもできます。

// home.component.ts

import { IGX_COMBO_DIRECTIVES } from 'igniteui-angular/combo';
// import { IGX_COMBO_DIRECTIVES } from '@infragistics/igniteui-angular'; for licensed package

@Component({
    selector: 'app-home',
    template: '<igx-combo></igx-combo>',
    styleUrls: ['home.component.scss'],
    standalone: true,
    imports: [IGX_COMBO_DIRECTIVES]
    /* or imports: [IgxComboComponent] */
})
export class HomeComponent {}

Ignite UI for Angular Combo モジュールまたはディレクティブをインポートしたので、igx-combo コンポーネントの使用を開始できます。

Angular ComboBox コンポーネントの使用

初期設定後、igx-combo をいくつかのデータにバインドします。

@Component({
    selector: 'app-combo-demo',
    template: '<igx-combo [data]="cities"></igx-combo>',
    styleUrls: ['combo-demo.component.scss'],
    standalone: true,
    imports: [IGX_COMBO_DIRECTIVES]
})
export class ComboDemo implements OnInit {
    public cities: { name: string, id: string }[] = [];

    public ngOnInit() {
        this.cities = [{ name: 'London', id: 'UK01' }, { name: 'Sofia', id: 'BG01'}, ...];
    }
}

コンボボックスは都市の配列にバインドされましたが、項目のテキストにどのプロパティを使用するか、値にどのプロパティを使用するかをコンポーネントにまだ伝えていません。これらを設定します。

データ値と表示プロパティ

コンボボックスは複雑なデータ (オブジェクト) の配列にバインドされているため、選択したアイテムを処理するためにコントロールが使用するプロパティを指定する必要があります。コントロールは、valueKey と displayKey の 2 つの @Input プロパティを公開します。

• valueKey - オプション、オブジェクト配列に推奨。 - コンボボックスの選択のために保存されるデータ エントリのプロパティを指定します。valueKey が省略された場合、コンボボックス値はデータ エントリへの参照を使用します (選択は igxCombo.data からのエントリの配列になります)。
• displayKey - オブジェクト配列に必須。 - アイテムのテキストに使用するプロパティを指定します。displayKey に値が指定されていない場合、コンボボックスは指定された valueKey (存在する場合) を使用します。

この例では、コンボボックスに各都市の name を表示し、コンボボックス値には各都市の id を格納します。そのため、これらのプロパティをコンボボックスの displayKey と valueKey にそれぞれ指定します。

<igx-combo [data]="cities" displayKey="name" valueKey="id"></igx-combo>

双方向バインディング

コンボボックス コンポーネントは、[(ngModel)] との双方向のデータ バインディングを完全にサポートし、テンプレート駆動フォームおよびリアクティブフォームでの使用もサポートします。コンボボックス選択には、双方向バインディングまたは選択 APIを使用してアクセスできます。コンボボックスの選択項目 (valueKey に基づく) と同じタイプの項目の配列を渡すことができ、いずれかが変更されるたびに、他方がそれに応じて更新されます。

以下の例では、都市 Sofia と London が最初に選択されます。コンボボックスの選択に対するその後の変更は、selectedCities 配列に反映されます。

<igx-combo [data]="cities" [(ngModel)]="selectedCities" displayKey="name" valueKey="id"></igx-combo>

export class MyCombo {
    public cities: { name: string, id: string }[] = [
                   { name: 'Sofia', id: 'BG01' }, { name: 'London', id: 'UK01' }, ...];
    public selectedCities: string[] = ['BG01', 'UK01'];
}

valueKey を指定しない場合も双方向バインディングを設定できます。たとえば、valueKey を省略すると、バインドされたモデルは次のようになります。

export class MyCombo {
    public cities: { name: string, id: string } [] = [
                   { name: 'Sofia', id: 'BG01' }, { name: 'London', id: 'UK01' }, ...];
    public selectedCities: { name: string, id: string } [] = [this.cities[0], this.cities[1]];
}

選択 API

コンボボックス コンポーネントは、コントロールの現在の選択状態を取得および操作できる API を公開します。

コンボボックスの選択を取得する 1 つの方法は、selection プロパティを使用することです。指定された valueKey (存在する場合) に応じて、選択された項目に対応する値の配列を返します。

例では、selection は選択された都市の id の配列を返します。

export class MyCombo {
    ...
    public selection: string[] = this.combo.selection;
}

選択 API を使用すると、ボタンのクリックや Observable の変更への応答などにより、ユーザーがコントロールを操作しなくても、コンボボックスの選択された項目を変更できます。たとえば、select() メソッドを使用して複数の都市を選択するボタンを実装できます。

<igx-combo [data]="cities" displayKey="name" valueKey="id"></igx-combo>
<button igxButton (click)="selectFavorites()">Select Favorites</button>

ボタンをクリックすると、都市 London と Sofia がコンボボックスの選択に追加されます。

export class MyExampleCombo {
    @ViewChild(IgxComboComponent, { read: IgxComboComponent, static: true })
    public combo: IgxComboComponent;
    ...
    selectFavorites(): void {
        this.combo.select(['UK01', 'BG01']);
    }
}

また、コンボボックスは、選択が変更されるたびに selectionChanging() イベントを発生させます。発行されたイベント引数 IComboSelectionChangingEventArgs には、変更前の選択、現在の選択、追加または削除された項目に関する情報が含まれています。また、イベントをキャンセルして、新しいアイテムの配列で選択を更新できないようにすることもできます。

イベントへのバインドは、igx-combo タグの適切な @Output プロパティを介して実行できます。

<igx-combo [data]="cities" displayKey="name" valueKey="id"
           (selectionChanging)="handleCityChange($event)">
</igx-combo>

以下の例では、都市が選択に追加または選択から削除されると、統計の可視化を更新するハンドラーが呼び出されます。

export class MyExampleCombo {
    ...
    handleCityChange(event: IComboSelectionChangingEventArgs): void {
        for (const item of event.added) {
            this.addToVisualization(item);
        }
        for (const item of event.removed) {
            this.removeFromVisualization(item);
        }
    }
}

また、コンボボックスは、選択が確定されてコンポーネントの状態が更新された後に Combo.selectionChanged イベントを発生させます。発行されたイベント引数 IComboSelectionChangedEventArgs には、以前の選択、現在の選択、および追加または削除されたアイテムに関する情報が含まれています。selectionChanging とは異なり、このイベントはキャンセル不可であり、最終的に確定した選択の状態を反映することが保証されています。コンボボックスが ngModel や Angular フォームとともに使用される場合、selectionChanged は値変更コールバックが呼び出された後に発行されます。

イベントへのバインドは、igx-combo タグの適切な @Output プロパティを介して行うことができます。

<igx-combo [data]="cities" displayKey="name" valueKey="id"
           (selectionChanged)="handleCitySelectionChanged($event)">
</igx-combo>

次の例では、選択が変更されると、ハンドラーが短い要約を更新し、追加および削除されたアイテムの数を追跡します。

export class MyExampleCombo {
    ...
    handleCitySelectionChanged(event: IComboSelectionChangedEventArgs): void {
        this.updateSelectionSummary(event.displayText, event.newSelection.length);

        for (const item of event.added) {
            this.highlightAddedCity(item);
        }

        for (const item of event.removed) {
            this.dimRemovedCity(item);
        }

        this.logSelectionTransition(event.oldSelection, event.newSelection);
    }
}

単一選択

デフォルトでは、Combo コントロールは複数選択を提供します。以下のスニペットは、ハンドラーを selectionChanging イベントにアタッチすることで、コンポーネントで単一選択を可能にする方法を示します。

<igx-combo [data]="lData" (selectionChanging)="singleSelection($event)"></igx-combo>

public singleSelection(event: IComboSelectionChangingEventArgs) {
    if (event.added.length) {
        event.newValue = event.added;
    }
}

注: 上記のように igxCombo を変更する代わりに、igxSimpleCombo を使用することをお勧めします。

キーボード ナビゲーション

コンボボックスが閉じていてフォーカスがある場合:

• 下矢印または Alt キー + 下矢印はコンボボックス ドロップダウンを開き、検索入力にフォーカスを移動します。

• Esc キーは、コンボボックスにフォーカスを保持したまま、選択された値をクリアします。

• Tab キーは、コンボボックスの外部にある次のフォーカス可能な要素へフォーカスを移動します。

コンボボックスが開いている場合:

• Esc キーは、リストを閉じてコンボボックスにフォーカスを保持します。

• Tab キーは、リストを閉じて次のフォーカス可能な要素にフォーカスを移動します。

コンボボックスを開いて検索入力にフォーカスがある場合:

• 上矢印または Alt キー + 上矢印はコンボボックス ドロップダウンを閉じ、フォーカスを閉じたコンボボックスに移動します。

• 下矢印は、フォーカスを検索入力から最初のリスト項目に移動します。リストが空でカスタム値が有効な場合、新しい項目の追加ボタンに移動します。

コンボボックスを開いてリスト項目にフォーカスがある場合:

• 下矢印は次のリスト項目に移動します。アクティブな項目がリストの最後の項目で、カスタム値が有効な場合、フォーカスは [項目の追加] ボタンに移動します。

• 上矢印は前のリスト項目に移動します。アクティブな項目がリストの最初の項目である場合、フォーカスは検索入力に戻ります。

• End キーは最後のリスト項目に移動します。

• Home キーは最初のリスト項目に移動します。

• Space キーはアクティブなリスト項目を選択/選択解除します。

• Enter キーはすでに選択した項目を確定し、リストを閉じます。

コンボボックスが開いていて、カスタム値が有効で、項目の追加ボタンにフォーカスがある場合:

• Enter キーは、検索入力のテキストと等しい valueKey と displayKey を持つ新しい項目を追加し、その項目を選択します。

• 上矢印は、フォーカスを最後のリスト項目に戻します。リストが空の場合は、検索入力に移動します。

スタイル設定

Combo テーマのプロパティ マップ

プライマリ プロパティを変更すると、関連するすべての依存プロパティが自動的に更新されます。

Ignite UI for Angular テーマを使用して、コンボボックスの外観を大幅に変更できます。はじめに、テーマ エンジンによって公開されている関数を使用するために、スタイル ファイルに index ファイルをインポートする必要があります。

@use "igniteui-angular/theming" as *;

// 重要: Ignite UI for Angular 13 より前のバージョンは、次を使用してください。
// @import '~igniteui-angular/lib/core/styles/themes/index';

最もシンプルな方法として、combo-theme を拡張する新しいテーマを作成します。$toggle-button-background を設定することで、テーマがボタンに適した状態の色とコントラストのある前景色を自動的に決定します。必要に応じて、$search-separator-border-color などの追加パラメーターを指定することも可能です。

$custom-combo-theme: combo-theme(
  $search-separator-border-color: #1d3743,
  $toggle-button-background: #57a5cd,
);

Combo は、項目コンテナーとして DropDown を内部使用します。IgxInputGroupComponent および IgxCheckboxComponent コンポーネントも含まれます。これらのコンポーネントのテーマを拡張する新しいテーマを作成し、それぞれのクラスの下にスコープすることで、コンボボックスのスタイル設定を変更できます。

$custom-drop-down-theme: drop-down-theme(
  $background-color: #57a5cd,
);

$custom-checkbox-theme: checkbox-theme(
  $border-radius: 10px,
  $fill-color: #1d3743,
  $empty-color: #1d3743,
);

最後にコンポーネントのテーマを含めます。

:host {
  @include tokens($custom-combo-theme);
  @include tokens($custom-drop-down-theme);
  @include tokens($custom-checkbox-theme);
}

デモ

Tailwind によるスタイル設定

カスタム Tailwind ユーティリティ クラスを使用して combo をスタイル設定できます。まず Tailwind を設定してください。

グローバル スタイルシートに Tailwind をインポートした上で、以下のように必要なテーマ ユーティリティを適用します:

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

ユーティリティ ファイルには、light テーマと dark テーマの両方のバリエーションが含まれています。

• light-* クラスはライト テーマ用です。
• dark-* クラスはダーク テーマ用です。
• プレフィックスの後にコンポーネント名を追加します (例: light-combo、dark-combo)。

これらのクラスを適用すると、動的なテーマの計算が可能になります。そこから、任意のプロパティを使用して、生成された CSS 変数をオーバーライドできます。コロンの後に、有効な CSS カラー形式 (HEX、CSS 変数、RGB など) を指定します。

プロパティの完全なリストは、combo-theme で確認できます。構文は次のとおりです:

<igx-combo
class="!light-combo
![--toggle-button-background:#99BAA6]
![--clear-button-foreground:#99BAA6]"
...></igx-combo>

最終的に、combo は次のようになります:

既知の問題

• 選択した項目を表示するコンボボックス入力は編集できません。ただし、FireFox のブラウザー仕様により、カーソルは表示されます。
• コンボボックスが undefined (例: [ undefined, ...]) を含むプリミティブ データの配列にバインドされる場合、undefined はドロップダウンに表示されません。複合データ (オブジェクトなど) の配列にバインドされ、valueKey に使用される値が undefined の場合、項目はドロップダウンに表示されますが、選択はできません。
• コンボボックスがリモート サービスにバインドされ、定義済みの選択がある場合、要求されたデータが読み込まれるまでその入力は空白のままになります。

API リファレンス

• Combo
• IgxComboComponent スタイル

その他の Angular コンポーネントおよびディレクティブ (またはそのいずれか) で使用した API:

• DropDown
• InputGroup
• Checkbox

テーマの依存関係

• IgxDropDown テーマ
• IgxIcon テーマ
• IgxCheckbox テーマ
• IgxOverlay テーマ

その他のリソース

• コンボボックス機能
• コンボボックス リモート バインディング
• コンボボックス テンプレート
• テンプレート駆動フォームの統合
• リアクティブ フォームの統合
• 単一選択コンボボックス

コミュニティに参加して新しいアイデアをご提案ください。

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