ListBox

ListBox は、リスト内の項目から 1 つ以上の値を選択するために使用されます。

インポート#


import { ListBox } from 'primereact/listbox';

基本#

ListBox は、options コレクションとともに、value と onChange プロパティを持つ制御コンポーネントとして使用されます。オプションのラベルと値は、それぞれ optionLabel と optionValue で定義します。プロパティで定義します。optionLabel のデフォルトのプロパティ名は label で、optionValue のデフォルトは value です。optionValue が省略され、オブジェクトに value プロパティがない場合、オブジェクト自体がオプションの値になります。オプションが文字列配列のような単純なプリミティブ値の場合、optionLabel と optionValue は必要ないことに注意してください。


<ListBox value={selectedCity} onChange={(e) => setSelectedCity(e.value)} options={cities} optionLabel="name" className="w-full md:w-14rem" />

複数選択#

ListBox はデフォルトで 1 つの項目を選択できます。複数選択する場合は multiple プロパティを有効にします。オプションの metaKeySelection が存在する場合、新しい項目を選択するにはメタキーが必要になるように動作が変更されます。


<ListBox multiple value={selectedCities} onChange={(e) => setSelectedCities(e.value)} options={cities} optionLabel="name" className="w-full md:w-14rem" />

グループ#

ネストされたデータ構造が提供されている場合、オプションをグループ化できます。グループのラベルを定義するには、optionGroupLabel プロパティが必要であり、グループの子を参照するプロパティを定義するには optionGroupChildren も必要です。


<ListBox value={selectedCity} onChange={(e) => setSelectedCity(e.value)} options={groupedCities} optionLabel="label" 
    optionGroupLabel="label" optionGroupChildren="items" optionGroupTemplate={groupTemplate} className="w-full md:w-14rem" listStyle={{ maxHeight: '250px' }} />

フィルター#

ListBox は filter プロパティを追加することで有効になる組み込みのフィルタリングを提供します。


<ListBox filter value={selectedCity} onChange={(e) => setSelectedCity(e.value)} options={cities} optionLabel="name" className="w-full md:w-14rem" />

テンプレート#

オプションのカスタムコンテンツは、オプションをパラメーターとして受け取る itemTemplate プロパティを使用して表示されます。追加で利用可能なテンプレートセクションは、filterTemplate と optionGroupTemplate です。


<ListBox value={selectedCountry} onChange={(e) => setSelectedCountry(e.value)} options={countries} optionLabel="name" 
    itemTemplate={countryTemplate} className="w-full md:w-14rem" listStyle={{ maxHeight: '250px' }} />

仮想スクロール#

VirtualScroller は、このデモのように 10 万件のレコードのような長いオプションリストを効率的にレンダリングするために使用されます。構成は virtualScrollerOptions プロパティで行います。ListBox で内部的に使用されているため、利用可能なオプションの詳細については、 VirtualScroller を参照してください。


<ListBox value={selectedItem} onChange={(e) => setSelectedItem(e.value)} options={items} 
    virtualScrollerOptions={{ itemSize: 38 }} className="w-full md:w-14rem" listStyle={{ height: '250px' }} />

無効#

無効状態は、検証に失敗したことを示すために invalid プロパティを使用して表示されます。フォーム検証ライブラリと統合する場合は、このスタイルを使用できます。


<ListBox invalid value={selectedCity} onChange={(e) => setSelectedCity(e.value)} options={cities} optionLabel="name" 
    className="w-full md:w-14rem" />

無効化#

disabled が存在する場合、要素は編集およびフォーカスできません。


<ListBox disabled options={cities} optionLabel="name" className="w-full md:w-14rem" />

アクセシビリティ#

スクリーンリーダー

コンポーネントを説明する値は、aria-labelledby または aria-label プロパティで提供できます。リスト要素には listbox ロールがあり、複数選択が有効な場合は aria-multiselectable 属性が true に設定されます。各リスト項目には option ロールがあり、aria-selected と aria-disabled が属性として設定されます。

フィルタリングが有効になっている場合、入力要素に aria-* プロパティを与えるように filterInputProps を定義できます。あるいは、filterPlaceholder も通常はスクリーンリーダーによって利用されます。


<span id="lb">Options</span>
<ListBox aria-labelledby="lb" />

<ListBox aria-label="City" />

キーボードサポート

キー	機能
tab	フォーカスは、選択されている最初のオプションに移動します。選択されていない場合は、最初のオプションにフォーカスが移動します。
上矢印	フォーカスは前のオプションに移動します。
下矢印	フォーカスは次のオプションに移動します。
enter	フォーカスされたオプションの選択状態を切り替えます。
space	フォーカスされたオプションの選択状態を切り替えます。
home	フォーカスは最初のオプションに移動します。
end	フォーカスは最後のオプションに移動します。
shift + 下矢印	フォーカスを次のオプションに移動し、選択状態を切り替えます。
shift + 上矢印	フォーカスを前のオプションに移動し、選択状態を切り替えます。
shift + space	最後に選択したオプションとフォーカスしたオプションの間の項目を選択します。
control + shift + home	フォーカスしたオプションと最初のオプションまでのすべてのオプションを選択します。
control + shift + end	フォーカスされているオプションと、最後のオプションまですべてのオプションを選択します。
control + a	すべてのオプションを選択します。