Web Components コンボボックスの概要

Web Components コンボボックスは、ユーザーが提供されたリストでさまざまな定義済みオプションを簡単に選択、フィルタリング、およびグループ化できるようにする軽量のエディターです。このコンポーネントは、Web Components コンボボックスキーボードナビゲーションのオプション、項目、ヘッダー、およびフッターの表示方法をカスタマイズするためのテンプレートもサポートしています。

Ignite UI for Web Components コンボボックスコンポーネントは、ユーザーが選択できるオプションのリストを提供します。仮想化された項目のリストにすべてのオプションが表示されます。つまり、コンボボックスは、1 つ以上のオプションを選択できる数千のレコードを同時に表示できます。さらに、このコンポーネントには、大文字と小文字を区別するフィルタリング、グループ化、複雑なデータバインディングなどの機能があります。

Web Components コンボボックスの例

Web Components コンボボックスコンポーネントを使用した作業の開始

まず、次のコマンドを実行して Ignite UI for Web Components をインストールする必要があります:

npm install igniteui-webcomponents

ComboBox コンポーネントを使用する前に、追加のコンポーネントおよび必要な CSS とともに登録する必要があります:

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

defineComponents(IgcComboComponent);

Ignite UI for Web Components の完全な概要については、作業の開始トピックを参照してください。

[!WARNING] IgcComboComponent コンポーネントは標準の <form> 要素では機能しません。代わりに IgcFormComponent を使用してください。

次に、オプションのリストを構築するコンボデータソースに、オブジェクトの配列をバインドします。

interface City {
    id: string;
    name: string;
}

const cities: City[] = [
    { name: 'London', id: 'UK01' },
    { name: 'Sofia', id: 'BG01'},
    { name: 'New York', id: 'NY01'}
];

export class Sample {
    private combo: IgcComboComponent<City>;

    constructor() {
        this.combo = document.getElementById('basic-combo') as IgcComboComponent<City>;
        this.combo.data = cities;
    }
}

<igc-combo id='basic-combo' display-key='name' value-key='id' value='["BG01"]'></igc-combo>

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

コンボは複雑なデータ (オブジェクト) の配列にバインドされている場合、コントロールが項目の選択を処理するために使用するプロパティを指定する必要があります。コンポーネントは以下のプロパティを公開します:

valueKey - オプション、複雑なデータオブジェクトに必須 - データソースのどのフィールドを選択に使用するかを決定します。valueKey が省略された場合、選択 API はオブジェクト参照を使用して項目を選択します。
displayKey - オプション、複雑なデータオブジェクトに推奨 - データソース内のどのフィールドが表示値として使用されるかを決定します。 displayKey に値が指定されていない場合、コンボは指定された valueKey (存在する場合) を使用します。この例では、コンボで各都市の name を表示し、項目の選択と各項目の基礎となる値として id フィールドを使用するようにします。したがって、これらのプロパティをコンボの valueKey と displayKey にそれぞれ提供します。

[!Note] データソースがプリミティブ型 (例: strings、numbers など) で構成されている場合、valueKey や displayKey を指定しないでください。

値の設定

ComboBox コンポーネントは、属性 (値とも呼ばれます) に加えて、value ゲッターとセッターを公開します。value 属性を使用して、コンポーネントの初期化時に選択した項目を設定できます。

値 (現在選択されている項目のリスト) を読み取る場合、または値を更新する場合は、それぞれ値ゲッターとセッターを使用します。値ゲッターは、valueKey で表される選択されたすべての項目のリストを返します。同様に、値セッターを使用して選択した項目のリストを更新する場合は、valueKey によって項目のリストを提供する必要があります。

例:

const combo = document.getElementById('basic-combo') as IgcComboComponent<City>;

// Given the overview example from above this will return ['BG01']
console.log(combo.value);

// Change the selected items to New York and London
combo.value = ['NY01', 'UK01'];

選択 API

コンボコンポーネントは、現在選択されている項目を変更できる API を公開します。

ユーザーの操作によってオプションのリストから項目を選択する以外に、プログラムで項目を選択することもできます。これは、select および deselect メソッドを介して行われます。項目の配列をこれらのメソッドに渡すことができます。メソッドが引数なしで呼び出された場合、呼び出されたメソッドに応じて、すべての項目が選択 / 選択解除されます。コンボコンポーネントに valueKey を指定した場合は、選択 / 選択解除する項目の値キーを渡す必要があります。

一部の項目を選択 / 選択解除:

// Select/deselect items by their IDs as valueKey is set to 'id'
combo.select(['BG01', 'BG02', 'BG03', 'BG04']);
combo.deselect(['BG01', 'BG02', 'BG03', 'BG04']);

すべての項目を選択 / 選択解除:

// Select/deselect all items
combo.select();
combo.deselect();

valueKey プロパティを省略した場合は、オブジェクト参照として選択 / 選択解除する項目を列挙する必要があります。

// Select/deselect values by object references when no valueKey is provided
combo.select([cities[1], cities[5]]);
combo.deselect([cities[1], cities[5]]);

検証

Ignite UI for Web Components Combo コンポーネントは、required、disabled、autofocus、invalid など、ほとんどの IgcInputComponent プロパティをサポートしています。このコンポーネントは、その検証にバインドされた 2 つのメソッドも公開しています。

reportValidity - 有効性をチェックし、コンポーネントが検証の制約を満たしている場合は true を返します。
checkValidity - ネイティブ入力 API に準拠するための reportValidity のラッパー。

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

コンボコンポーネントがフォーカスされていて、オプションのリストが表示されていない場合:

↓ / Alt + ↓ キーを使用してオプションのリストを開きます。

コンボコンポーネントがフォーカスされ、オプションのリストが表示されている場合:

↓ キーを使用すると、リスト内の次の項目がアクティブになります。
↑ キーを使用すると、リスト内の前の項目がアクティブになります。最初の項目がすでにアクティブな場合、入力にフォーカスします。
Home または End キーを使用すると、リストの最初または最後の項目がアクティブになります。
Space キーを使用すると、アクティブな項目が選択されます。
Enter キーを使用すると、アクティブな項目が選択され、オプションのリストが閉じます。
Esc または Tab/Shift + Tab キーを使用すると、オプションのリストが閉じます。

コンボのスタイル設定

Ignite UI for Web Components IgcComboComponent コンポーネントとその項目の外観は、以下に示す公開 CSS パーツを使用して変更できます。

CSS パーツ

パーツ名	説明
`label`	カプセル化されたテキストラベル。
`input`	メイン入力フィールド。
`native-input`	メイン入力フィールドのネイティブ入力。
`prefix`	プレフィックスラッパー。
`suffix`	サフィックスラッパー。
`toggle-icon`	トグルアイコンラッパー。
`clear-icon`	クリアアイコンラッパー。
`case-icon`	フィルター入力のサフィックス内のコンテンツを描画するケースアイコンラッパー。
`helper-text`	ヘルパーテキストラッパー。
`search-input`	検索入力フィールド。
`list-wrapper`	オプションラッパーのリスト。
`list`	オプションボックスのリスト。
`item`	オプションのリスト内の各項目を表します。
`group-header`	オプションのリストの各ヘッダーを表します。
`active`	項目がアクティブな場合に、項目パーツリストに追加されます。
`selected`	項目が選択されている場合に、項目パーツリストに追加されます。
`checkbox`	各リスト項目の各チェックボックスを表します。
`checkbox-indicator`	各リスト項目のチェックボックスインジケーターを表します。
`checked`	チェックボックスがチェックされている場合に、チェックボックスパーツリストに追加されます。
`header`	ヘッダーコンテンツを保持するコンテナー。
`footer`	フッターコンテンツを保持するコンテナー。
`empty`	空のコンテンツを保持するコンテナ。

API リファレンス

IgcComboComponent