Angular Single Select ComboBox (単一選択のコンボボックス) コンポーネントの概要
Angular Single Select ComboBox コンポーネントは、単一の選択を可能にする ComboBox コンポーネントの変更です。これを「シンプルなコンボ」と呼びます。元の 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';
// 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';
// 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 が cities の配列にバインドされました。
データ値と表示プロパティ
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>
Note
データ ソースが単純なタイプ (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 を使用すると、ユーザーがコントロールを操作せずに、Simple ComboBox の選択された項目を変更することもできます (ボタンのクリックを介して、Observable の変更への応答としてなどです)。たとえば、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 を閉じてフォーカスを合わせると、次のようになります:
ArrowDownまたはAlt + ArrowDownは、Simple ComboBox のドロップダウンを開きます。
Note
その他のキー ストロークはすべて入力によって処理されます。
Simple ComboBox が開かれ、リスト項目がフォーカスされている場合:
下矢印は次のリスト項目に移動します。アクティブな項目がリストの最後の項目で、カスタム値が有効な場合、フォーカスは [項目の追加] ボタンに移動します。上矢印は前のリスト項目に移動します。アクティブな項目がリストの最初の項目である場合、フォーカスは検索入力に戻り、入力内のすべてのテキストも選択されます。Endは最後のリスト項目に移動します。Homeは最初のリスト項目に移動します。Spaceキーはアクティブなリスト項目を選択/選択解除します。Enterを押すと、アクティブなリスト項目が選択/選択解除され、リストが閉じます。Escはリストを閉じます。
コンボボックスを開くと、カスタム値が有効になり、項目の追加ボタンがフォーカスされます。
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 リモート バインディングで説明されている手順に従うリモート バインディングを示しています。
Angular Simple ComboBox のスタイル設定
Ignite UI for Angular Theming を使用すると、Simple ComboBox の外観を大幅に変更できます。はじめに、テーマ エンジンによって公開されている関数を使用するために、スタイル ファイルに index ファイルをインポートする必要があります。
@use 'igniteui-angular/theming' as *;
最も単純なアプローチに従って、combo-theme を拡張し、$empty-list-background パラメーターを受け入れる新しいテーマを作成します。
$custom-simple-combo-theme: combo-theme(
$empty-list-background: #1a5214
);
IgxSimpleComboComponent は、IgxDropDownComponent を項目コンテナーとして内部的に使用します。IgxInputGroup コンポーネントも含まれています。これらのコンポーネントのテーマを拡張する新しいテーマを作成し、それぞれのクラスの下でそれらをスコープすると、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 ::ng-deep {
@include css-vars($custom-combo-theme);
@include css-vars($custom-drop-down-theme);
}
Note
IgxSimpleCombo コンポーネントは、IgxOverlay サービスを使用して、Simple ComboBox 項目リスト コンテナーを保持および表示します。スタイルを適切にスコープするには、OverlaySetting.outlet を使用してください。詳細については、IgxOverlay スタイル ガイドを確認してください。
Note
IgxSimpleCombo のデフォルトのタイプは、line である IgxSelect とは異なり box です。
サンプル
既知の問題
- Simple ComboBox には、高さのサイズを設定するための入力がありません。将来、IgxInputGroup コンポーネントは、カスタムのサイズ変更オプションを公開し、IgxSimpleCombo は適切なスタイル設定と外観の統一に同じ機能を使用します。
- シンプルなコンボボックスが
undefined(例:[ undefined, ...]) を含むプリミティブ データの配列にバインドされる場合、undefinedはドロップダウンに表示されません。複合データ (オブジェクトなど) の配列にバインドされ、valueKeyに使用される値がundefinedの場合、項目はドロップダウンに表示されますが、選択はできません。 - シンプルなコンボボックスが
ngModelでバインドされ、requiredとマークされている場合、null、undefined、''の値は選択できません。 - シンプルなコンボボックスがリモート サービスにバインドされ、定義済みの選択がある場合、要求されたデータが読み込まれるまでその入力は空白のままになります。
Note
Simple ComboBox は内部で igxForOf ディレクティブを使用するため、すべての igxForOf 制限は Simple ComboBox に対して有効です。詳細については、igxForOf 既知の制限 の既知の問題のセクションを参照してください。
API まとめ
その他のコンポーネントおよびディレクティブ (またはそのいずれか) で使用した API:
テーマの依存関係
その他のリソース
コミュニティに参加して新しいアイデアをご提案ください。
GitHub