Combo (コンボ) コンポーネントの機能
Web Components Combo は、ローカル データへのバインド、ユーザーの入力に応じたオプションのフィルタリング、データ フィールドによるグループ化に対応し、無効にすることもできます。
Combo は、リモート サービスからオプションを 1 ページずつ読み込むこともできます。
ライブ デモ
機能
データ バインディング
次のスニペットは、data プロパティを使用して Web Components Combo を米国の州のローカル リストにバインドし、各州のコードを保持して州名を表示します。Combo が各項目から読み取るキーについては、Combo の概要トピックのデータ バインディングを参照してください。
<igc-combo id="combo" value-key="id" display-key="name"></igc-combo>
import { IgcComboComponent } from 'igniteui-webcomponents';
import { UsState, usStates } from './ComboData';
// Items such as { id: 'CT', name: 'Connecticut', region: 'New England' }
const combo = document.getElementById('combo') as IgcComboComponent<UsState>;
combo.data = usStates;
リモート バインディング
Web Components Combo は、リモート サービスからオプションを 1 ページずつ読み込めます。検索とページングはサービスがサーバー上で行い、Combo はまだ読み込まれていない各項目のプレースホルダーを表示します。次のサンプルは、ユーザーのスクロールや検索に合わせて、リモート サービスから製品を読み込みます。
リモート バインディングには igniteui-webcomponents 7.5.0 以降が必要です。
Combo をリモート サービスにバインド
igniteui-webcomponents/extras/combo-data-source から bindComboDataSource() をインポートし、Combo と load() 関数を持つソースを渡します。バインディングは、searchText、caseSensitive、startIndex、count を保持するリクエストと AbortSignal を指定して、ページごとに load() を呼び出します。load() からは、そのページの項目と、一致する項目の合計数を返してください。
<igc-combo id="combo" label="Products" value-key="ProductID" display-key="ProductName"></igc-combo>
import { defineComponents, IgcComboComponent } from 'igniteui-webcomponents';
import { bindComboDataSource } from 'igniteui-webcomponents/extras/combo-data-source';
defineComponents(IgcComboComponent);
interface Product {
ProductID: number;
ProductName: string;
}
const url = 'https://services.odata.org/V4/Northwind/Northwind.svc/Products';
const combo = document.getElementById('combo') as IgcComboComponent<Product>;
const binding = bindComboDataSource(combo, {
// Loads one page of the products that match the search text.
load: async ({ searchText, startIndex, count }, signal) => {
let query = `?$skip=${startIndex}&$top=${count}&$count=true`;
if (searchText) {
// Double the apostrophes for OData, then encode the text for the URL.
const text = encodeURIComponent(searchText.replace(/'/g, "''"));
query += `&$filter=contains(ProductName, '${text}')`;
}
// The signal lets a newer search abort this request.
const response = await fetch(`${url}${query}`, { signal });
const data = await response.json();
return { items: data.value, totalCount: data['@odata.count'] };
}
}, {
// The service returns up to 20 products per request.
pageSize: 20
});
バインディングは Combo をリモート フィルタリングに切り替え、次のようにリクエストを行います。
- 項目のないリストをユーザーが開いたときに最初のページを読み込み、ユーザーが検索入力への入力を止めた後にも最初のページを読み込み直します。
- ユーザーが読み込み済みの項目の末尾付近までスクロールすると、次のページを追加します。
load()がfetch()に渡すシグナルによって、新しい検索で古くなったリクエストを中止します。- Combo の
totalItemCountプロパティに合計数を設定し、検索の待機中またはページの読み込み中はloadingプロパティを設定します。
Combo が保持する項目数が totalItemCount より少ない間、リストはまだ読み込まれていない各項目のプレースホルダーを表示するため、スクロール バーには結果の全長が反映されます。loading が設定されている間、Combo はトグル アイコンの代わりにスピナーを表示します。スピナーは loading スロットで置き換え、スピナーとプレースホルダーのスタイルは loading および placeholder CSS パーツで設定します。
bindComboDataSource() の 3 番目の引数でバインディングを構成します。
| オプション | 既定値 | 説明 |
|---|---|---|
pageSize |
50 |
1 回のリクエストで読み込む項目の最小数。ソースはこれより少ない数 (サーバーのページ上限までなど) を返すこともでき、その場合 Combo は残りを要求します。 |
debounce |
300 |
入力が止まってから検索を読み込むまでの待機時間 (ミリ秒)。 |
loadOnOpen |
true |
項目のないリストをユーザーが開いたときに最初のページを読み込むかどうか。 |
onError |
- | 失敗したリクエストのエラーを受け取ります。Combo は読み込み済みの項目を保持します。 |
bindComboDataSource() は、2 つのメソッドを持つバインディングを返します。refresh() は現在の検索の最初のページを再度読み込みます。コードで filteringOptions.caseSensitive を変更した後に呼び出してください。dispose() はリスナーを削除し、進行中のリクエストを中止して、Combo のフィルタリング モードを元に戻します。
リモート フィルタリング モード
bindComboDataSource() は Combo のパブリック API のみを使用します。リクエストを自分で行うには、filteringOptions の mode に remote を設定します。
combo.filteringOptions = { mode: 'remote' };
リモート モードでは、Combo は検索をサービスに任せます。
- Combo はオプションをフィルタリングしなくなります。
igcSearchInputイベントのdetail.searchTextを読み取り、サーバーで検索して、dataに結果の最初のページを設定します。一致の判定はサーバーが行うため、検索と一緒にfilteringOptions.caseSensitiveを送信してください。 - ユーザーが
dataの末尾付近までスクロールすると、igcDataRequestイベントがdetail.startIndexからdetail.count件の追加項目を要求します。それらをdataに追加します。 totalItemCountに結果の合計数を設定し、リクエストの実行中はloadingを設定します。
選択の処理
Combo がリモート データを読み込む場合は、valueKey を設定します。ページごとに新しいオブジェクトが作成され、Combo は選択された項目とそれらのオブジェクトをそのキーの値で照合します。新しい data を設定しても選択は保持されます。検索結果に選択された項目が含まれない場合も選択されたままとなり、後のページや検索に含まれると再び選択済みとして表示されます。
保存済みフィルターの値など、どのページにもまだ項目が読み込まれていない値を選択するには、bindComboDataSource() のソースに resolve() 関数を追加します。バインディングはそれらの値を指定して resolve() を呼び出し、返された項目を選択します。
Combo は、選択された項目をサーバーが削除したのか、その項目を含むページをまだ送信していないだけなのかを判別できません。ライブ データを再度読み込むときは、サーバーに存在しなくなった選択済み項目に対して deselect() を呼び出してください。
フィルタリング
Web Components Combo は、ユーザーがドロップダウンの検索入力に入力するのに合わせて、オプションのリストをフィルタリングします。フィルタリングは既定で有効です。disableFiltering を設定するとフィルタリングが無効になり、検索入力も非表示になります。
ユーザーが検索の大文字と小文字の区別を切り替えられるようにするには、caseSensitiveIcon を設定します。これにより、Combo の検索入力に大文字と小文字を区別するアイコンが表示されます。フィルタリングが無効な間は検索入力が非表示のため、このアイコンは効果がありません。
<!-- Shows the case-sensitive icon in the search input -->
<igc-combo case-sensitive-icon></igc-combo>
<!-- Turns filtering off, which also hides the search input -->
<igc-combo disable-filtering></igc-combo>
フィルタリング オプション
filteringOptions プロパティは、Web Components Combo が検索テキストを照合する方法を構成します。
filterKey- 検索対象のデータ フィールド。既定値はdisplayKeyで設定されたフィールドです。caseSensitive- 検索で大文字と小文字を区別するかどうか。既定値はfalseです。大文字と小文字を区別するアイコンがこの値を切り替えます。matchDiacritics- アクセント付き文字を自身にのみ一致させるかどうか。trueの場合、éはeに一致しません。既定値はfalseです。
次のスニペットでは、各州の名前ではなく地域を検索対象にし、大文字と小文字を区別して検索します。
combo.filteringOptions = {
filterKey: 'region',
caseSensitive: true
};
検索入力のフォーカス
Web Components Combo のドロップダウンが開くと、検索入力にフォーカスが移ります。
autofocusList を設定すると、代わりにオプションのリストにフォーカスが移ります。これにより、モバイル デバイスでは、ドロップダウンと同時にソフトウェア キーボードが開くのを防げます。
<igc-combo autofocus-list></igc-combo>
グループ化
groupKey にデータ項目のフィールドを設定すると、Web Components Combo のオプションがそのフィールドの値ごとにヘッダーの下にグループ化されます。
<igc-combo group-key="region"></igc-combo>
groupKey プロパティは、データ項目がオブジェクトの場合にのみ有効です。
並べ替え方向
groupSorting プロパティは、Web Components Combo 内のグループの順序を設定します。asc (既定) は昇順、desc は降順に並べ替え、none は各グループの先頭の項目がデータ内に現れる順にグループを並べます。各グループ内の項目は、データ内の順序のままです。
<igc-combo group-sorting="desc"></igc-combo>
クリア ボタン
Web Components Combo は、少なくとも 1 つのオプションが選択されている間、入力フィールド内にクリア ボタンを表示し、このボタンをクリックすると選択がクリアされます。ボタンを非表示にするには、disableClear を設定します。
<igc-combo disable-clear></igc-combo>
オートフォーカス
autofocus を設定すると、ページの読み込み時に Web Components Combo にフォーカスが移ります。
<igc-combo autofocus></igc-combo>
スクロール方法
scrollStrategy プロパティは、ドロップダウンが開いている間に Combo を囲むコンテナーがスクロールしたときの、Web Components Combo のドロップダウンの動作を設定します。hide (既定) は入力フィールドが表示範囲外にある間ドロップダウンを非表示にし、scroll はドロップダウンを開いたまま入力フィールドに追従させ、close はドロップダウンを閉じます。
<igc-combo scroll-strategy="close"></igc-combo>
API リファレンス
Web Components Combo の完全な API リファレンスを参照してください。
その他のリソース
Combo の詳細については、次の Web Components リソースを参照してください。