React コンボボックスの概要

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

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

React コンボボックスの例

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

まず、次のコマンドを実行して、対応する Ignite UI for React npm パッケージをインストールする必要があります:

npm install igniteui-react

次に、以下のように、React IgrCombo と必要な CSS をインポートする必要があります:

import { IgrCombo } from 'igniteui-react';
import 'igniteui-webcomponents/themes/light/bootstrap.css';

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

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

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

<IgrCombo
    valueKey="id"
    displayKey="name"
    data={cities}
    value={["BG01"]}
></IgrCombo>

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

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

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

値の設定

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

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

const comboRef = useRef<IgrCombo>(null);

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

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

選択 API

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

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

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

// Select/deselect items by their IDs as valueKey is set to 'id'
comboRef.current.select(["UK01", "UK02", "UK03", "UK04", "UK05"]);
comboRef.current.deselect(["UK01", "UK02", "UK03", "UK04", "UK05"]);

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

// Select/deselect all items
comboRef.current.select([]);
comboRef.current.deselect([]);

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

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

検証

Ignite UI for React Combo コンポーネントは、Required、Disabled、Autofocus、Invalid など、ほとんどの IgrInput プロパティをサポートしています。このコンポーネントは、その検証にバインドされた 2 つのメソッドも公開しています。

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

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

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

• ↓ または ALT + ↓ キーを使用してオプションのリストを開きます。

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

• ↓ キーを使用すると、リスト内の次の項目がアクティブになります。
• ↑ キーを使用すると、リスト内の前の項目がアクティブになります。最初の項目がすでにアクティブな場合、入力にフォーカスします。
• HOME または END キーを使用すると、リストの最初または最後の項目がアクティブになります。
• SPACE キーを使用すると、アクティブな項目が選択されます。
• ENTER キーを使用すると、アクティブな項目が選択され、オプションのリストが閉じます。
• ESC または TAB/SHIFT + TAB キーを使用すると、オプションのリストが閉じます。

スタイル設定

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

CSS パーツを使用すると、コンボのスタイルを完全に制御できます。

igc-combo::part(search-input) {
  background-color: var(--ig-gray-100);
  border-radius: 2px;
}

igc-combo::part(input) {
  background-color: var(--ig-gray-100);
}

igc-combo::part(prefix) {
  background-color: var(--ig-secondary-50);
  color: var(--ig-primary-500);
}

igc-combo::part(toggle-icon) {
  color: var(--ig-primary-500);
}

API リファレンス

その他のリソース

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