Open Source

Angular Single Select ComboBox (単一選択のコンボボックス) コンポーネントの概要

Angular Single Select ComboBox コンポーネントは、ComboBox コンポーネントを単一選択用に変更したものです。このコンポーネントを Simple Combo と呼びます。元の ComboBox コンポーネントの単一選択モードに対する需要が高かったため、ユーザーが事前定義された項目リストからオプションを選択し、カスタム値を入力できるようにする、テキストを入力して検索できる入力フィールドを備えた拡張コンポーネントを作成しました。

Angular Simple ComboBox の例

この Angular Simple ComboBox の例では、ユーザーがチャートのトレンドラインタイプを選択する方法を確認できます。さらに、Simple ComboBox は、キーボードナビゲーションとカスタムスタイル設定機能を公開します。

Angular Simple ComboBox の機能

Simple ComboBox コントロールは、次の機能を公開します:

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

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

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

ng add igniteui-angular

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

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

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

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

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

// home.component.ts

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

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

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

Angular Simple ComboBox の使用

通常のコンボボックスと同様に、igx-simple-combo をデータにバインドできます。

export class MySimpleComboComponent implements OnInit {
    public cities: City[];

    public ngOnInit() {
        this.cities = getCitiesByPopulation(10000000);
    }
}

<igx-simple-combo [data]="cities"></igx-simple-combo>

これで、Simple ComboBox が都市の配列にバインドされました。

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

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

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

この場合、Simple ComboBox に各都市の name を表示し、Simple ComboBox の値に各都市の id を保存する必要があります。そのため、これらのプロパティを値として Simple ComboBox の displayKey と valueKey にそれぞれバインドします。

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

データソースが単純なタイプ (string[]、number[] など)で構成されている場合、valueKey と displayKey を指定しないでください。

双方向バインディング

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

次の例では、提供されたデータの最初の都市が最初に選択されます。Simple ComboBox の選択をさらに変更すると、selectedCities に反映されます。

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

export class MySimpleComboComponent implements OnInit {
    public cities: City[];
    public selectedCity: number;

    public ngOnInit(): void {
        this.cities = getCitiesByPopulation(10000000);
        this.selectedCity = this.cities[0].id;
    }
}

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

export class MySimpleComboComponent {
    public cities: City[] = [
                   { name: 'Sofia', id: '1' }, { name: 'London', id: '2' }, ...];
    public selectedCity: City = this.cities[0];
}

選択 API

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

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

この例では、selection は選択された都市の id を返します:

export class MySimpleComboComponent {
    ...
    public selection: string = this.simpleCombo.selection;
}

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

<igx-simple-combo [data]="cities" [displayKey]="'name'" [valueKey]="'id'"></igx-simple-combo>
<button igxButton (click)="selectFavorite()">Select Favorite</button>

ボタンをクリックすると、London が Simple ComboBox の選択に追加されます。

export class MySimpleComboComponent {
    @ViewChild(IgxSimpleComboComponent, { read: IgxSimpleComboComponent, static: true })
    public simpleCombo: IgxSimpleComboComponent;
    ...
    selectFavorites(): void {
        this.simpleCombo.select('2');
    }
}

Simple ComboBox は、選択が変更されるたびに selectionChanging イベントを発生させます。発行されたイベント引数 ISimpleComboSelectionChangingEventArgs には、変更前の選択、現在の選択、および表示された項目に関する情報が含まれています。イベントをキャンセルして、選択が行われないようにすることもできます。

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

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

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

Simple ComboBox が閉じていてフォーカスがある場合:

下矢印または Alt キー + 下矢印は、Simple ComboBox のドロップダウンを開きます。
Esc キーは、コンボボックスにフォーカスを保持したまま、選択された値をクリアします。
Tab キーは、コンボボックスの外部にある次のフォーカス可能な要素へフォーカスを移動します。

その他のキーストロークはすべて入力によって処理されます。

Simple ComboBox が開いていて、リスト項目にフォーカスがある場合:

下矢印 は次のリスト項目に移動します。アクティブな項目がリストの最後の項目で、カスタム値が有効な場合、フォーカスは [項目の追加] ボタンに移動します。
上矢印 は前のリスト項目に移動します。アクティブな項目がリストの最初の項目である場合、フォーカスは検索入力に戻り、入力内のすべてのテキストも選択されます。
End は最後のリスト項目に移動します。
Home は最初のリスト項目に移動します。
Space キーはアクティブなリスト項目を選択/選択解除します。
Enter を押すと、アクティブなリスト項目が選択/選択解除され、リストが閉じます。
Esc キーは、リストを閉じてコンボボックスにフォーカスを保持します。
Tab キーは、リストを閉じて次のフォーカス可能な要素にフォーカスを移動します。

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

Enter キーは、検索入力のテキストと等しい valueKey と displayKey を持つ新しい項目を追加し、その項目を選択します。
上矢印 はフォーカスを最後のリスト項目に戻すか、あるいはリストが空の場合はフォーカスを入力に移動します。

カスケーディング

次のサンプルは、igx-simple-combo が使用されるシナリオを示しています。

カスケードコンボを使用した Angular Grid のサンプルを参照してください。

テンプレートの構成

Simple ComboBox の API を使用して、あるコンポーネントから選択した項目を取得し、次のコンポーネントのデータソースを読み込んで、必要に応じて選択とデータソースをクリアします。

<igx-simple-combo #country
    [data]="countriesData"
    (selectionChanging)="countryChanging($event)"
    placeholder="Choose Country..."
    [(ngModel)]="selectedCountry"
    [displayKey]="'name'">
</igx-simple-combo>
<igx-simple-combo #region
    [data]="regionData"
    (selectionChanging)="regionChanging($event)"
    placeholder="Choose Region..."
    [(ngModel)]="selectedRegion"
    [displayKey]="'name'"
    [disabled]="regionData.length === 0">
</igx-simple-combo>
<igx-simple-combo #city
    [data]="citiesData"
    placeholder="Choose City..."
    [(ngModel)]="selectedCity"
    [displayKey]="'name'"
    [disabled]="citiesData.length === 0">
</igx-simple-combo>

コンポーネント定義

export class SimpleComboCascadingComponent implements OnInit {
    public selectedCountry: Country;
    public selectedRegion: Region;
    public selectedCity: City;
    public countriesData: Country[];
    public regionData: Region[] = [];
    public citiesData: City[] = [];
    public ngOnInit(): void {
        this.countriesData = getCountries(['United States', 'Japan', 'United Kingdom']);
    }

    public countryChanging(e: ISimpleComboSelectionChangingEventArgs) {
        this.selectedCountry = e.newSelection as Country;
        this.regionData = getCitiesByCountry([this.selectedCountry?.name])
            .map(c => ({name: c.region, country: c.country}))
            .filter((v, i, a) => a.findIndex(r => r.name === v.name) === i);
        this.selectedRegion = null;
        this.selectedCity = null;
        this.citiesData = [];
    }

    public regionChanging(e: ISimpleComboSelectionChangingEventArgs) {
        this.selectedRegion = e.newSelection as Region;
        this.citiesData = getCitiesByCountry([this.selectedCountry?.name])
            .filter(c => c.region === this.selectedRegion?.name);
        this.selectedCity = null;
    }
}

Angular Simple ComboBox リモートバインディング

Ignite UI for Angular Simple ComboBox コンポーネントは、コンボボックスをリモートサービスにバインドし、要求に応じてデータを取得できる API を公開します。

デモ

以下のサンプルは、dataPreLoad プロパティを使用してリモートデータの新しいチャンクをロードし、ComboBox リモートバインディングで説明されている手順に従うリモートバインディングを示しています。

スタイル設定

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

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

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

最も単純なアプローチに従って、combo-theme を拡張し、$empty-list-background パラメーターを受け入れる新しいテーマを作成します。

$custom-simple-combo-theme: combo-theme(
  $empty-list-background: #1a5214
);

SimpleCombo は、DropDown を項目コンテナーとして内部的に使用します。InputGroup コンポーネントも含まれています。これらのコンポーネントのテーマを拡張する新しいテーマを作成し、それぞれのクラスの下でそれらをスコープすると、Simple ComboBox のスタイルを変更できます。

$custom-drop-down-theme: drop-down-theme(
  $background-color: #d9f5d6,
  $header-text-color: #1a5214,
  $item-text-color: #1a5214,

  $focused-item-background: #72da67,
  $focused-item-text-color: #1a5214,
  $hover-item-background: #a0e698,
  $hover-item-text-color: #1a5214,

  $selected-item-background: #a0e698,
  $selected-item-text-color: #1a5214,
  $selected-hover-item-background: #72da67,
  $selected-hover-item-text-color: #1a5214,
  $selected-focus-item-background: #72da67,
  $selected-focus-item-text-color: #1a5214,
);

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

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

SimpleCombo は、IgxOverlay サービスを使用してリストを表示します。表示のカプセル化 (View Encapsulation) の設定や、生成されるセレクターが一致する必要がある場所によっては、ローカルでのテーマの include に引き続き ::ng-deep が必要になる場合があります。また、デフォルトのデタッチされたアウトレットにアタッチされたリストは、コンボのホストからスタイルを継承できません。テーマを適用したコンテナーの下に OverlaySettings.outlet を構成するか、アウトレットに一致するセレクターからテーマを出力してください。詳細については、IgxOverlay スタイルガイドを参照してください。 [!Note] IgxSimpleCombo のデフォルトの type は box です。これは、デフォルトが line である IgxSelect とは異なります。

デモ

既知の問題

Simple ComboBox には、高さのサイズを設定するための入力がありません。将来、InputGroup コンポーネントは、カスタムのサイズ変更オプションを公開し、SimpleCombo は適切なスタイル設定と外観の統一に同じ機能を使用します。
Simple ComboBox が undefined (例: [ undefined, ...]) を含むプリミティブデータの配列にバインドされる場合、undefined はドロップダウンに表示されません。複合データ (オブジェクトなど) の配列にバインドされ、valueKey に使用される値が undefined の場合、項目はドロップダウンに表示されますが、選択はできません。
Simple ComboBox が ngModel でバインドされ、required とマークされている場合、null、undefined、'' の値は選択できません。
Simple ComboBox がリモートサービスにバインドされ、定義済みの選択がある場合、要求されたデータが読み込まれるまでその入力は空白のままになります。

Simple ComboBox は内部でリストの仮想化に Virtual Scroll コンポーネントを使用するため、すべての Virtual Scroll の制限が Simple ComboBox に対して有効です。詳細については、Virtual Scroll の既知の制限セクションを参照してください。

API リファレンス

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

テーマの依存関係

その他のリソース

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