React コンボボックスの概要

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

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

    React コンボボックスの例

    EXAMPLE
    TSX
    CSS
    Edit in:

    このサンプルが気に入りましたか? 完全な Ignite UI for Reactツールキットにアクセスして、すばやく独自のアプリの作成を開始します。無料でダウンロードできます。

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

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

    npm install igniteui-react
cmd

    次に、以下のように、React ComboBox とそれに必要な CSS をインポートし、そのモジュールを登録する必要があります:

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

IgrComboModule.register();
tsx

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

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

    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>
tsx

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

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

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

    データ ソースがプリミティブ型 (例: strings、numbers など) で構成されている場合、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'];
tsx

    選択 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"]);
tsx

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

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

    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]]);
tsx

    EXAMPLE
    DATA
    TSX
    CSS
    Edit in:

    検証

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

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

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

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

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

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

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

    スタイル設定

    IgrCombo コンポーネントとその項目の外観は、以下に示す公開 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 空のコンテンツを保持するコンテナー。

    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);
}
css

    EXAMPLE
    DATA
    TSX
    CSS
    Edit in:

    API リファレンス

    その他のリソース