オートコンプリート

オートコンプリートは、入力中にリアルタイムで候補を表示する入力コンポーネントです。

インポート#


import { AutoComplete } from 'primereact/autocomplete';

基本#

オートコンプリートは、_value_ プロパティと _onChange_ プロパティを使用して制御されたコンポーネントとして使用されます。さらに、結果を照会するには、_suggestions_ と _completeMethod_ が必要です。


<AutoComplete value={value} suggestions={items} completeMethod={search} onChange={(e) => setValue(e.value)}  />

ドロップダウン#

_dropdown_ プロパティを有効にすると、入力フィールドの横にボタンが表示されます。ボタンのクリック動作は、_dropdownMode_ プロパティを使用して定義されます。このプロパティは、可能な値として **blank** または **current** を取ります。 _blank_ は空の文字列でクエリを送信するデフォルトモードですが、_current_ 設定は入力の現在の値でクエリを送信します。


<AutoComplete value={value} suggestions={items} completeMethod={search} onChange={(e) => setValue(e.value)} dropdown />

オブジェクト#

オートコンプリートは、候補として表示するラベルを定義する _field_ プロパティを使用してオブジェクトを操作できます。モデルに渡される値は、依然として候補のオブジェクトインスタンスです。 _｛name: "United States", code:"USA"｝_ のような name フィールドと code フィールドを持つ Country オブジェクトの例を次に示します。


<AutoComplete field="name" value={selectedCountry} suggestions={filteredCountries} completeMethod={search} onChange={(e) => setSelectedCountry(e.value)} />

テンプレート#

カスタムコンテンツは、_itemTemplate_ プロパティを使用してオプションとして表示できます。このプロパティは、候補オプションをパラメーターとして持ち、要素を返す関数を参照します。同様に、_selectedItemTemplate_ プロパティは、同じアプローチを使用して複数モードでチップをカスタマイズするために使用できます。 _selectedItemTemplate_ は、現時点では複数モードでのみ使用できることに注意してください。


<AutoComplete field="name" value={selectedCountry} suggestions={filteredCountries}  
    completeMethod={search} onChange={(e) => setSelectedCountry(e.value)} itemTemplate={itemTemplate} panelFooterTemplate={panelFooterTemplate} />

グループ#

オプショングループは、_optionGroupLabel_ プロパティと _optionGroupChildren_ プロパティで指定されます。


<AutoComplete value={selectedCity} onChange={(e) => setSelectedCity(e.value)} suggestions={filteredCities} completeMethod={search}
        field="label" optionGroupLabel="label" optionGroupChildren="items" optionGroupTemplate={groupedItemTemplate} placeholder="Hint: type 'a'" />

強制選択#

ForceSelection モードは、手動入力を検証して、候補リストにも存在するかどうかを確認します。存在しない場合、入力値はクリアされ、モデルに渡される値が常に候補の1つであることが確認されます。有効にするだけです _forceSelection_ は、入力が常に候補リストからのものであることを強制します。


<AutoComplete value={value} suggestions={items} completeMethod={search} onChange={(e) => setValue(e.value)} forceSelection />

仮想スクロール#

仮想スクロールは、大きなリストをレンダリングするための高性能な方法です。スクロール動作の設定は、_virtualScrollerOptions_ で定義されます。これには、アイテムの高さを設定するための必須値として _itemSize_ が必要です。設定 API の詳細については、VirtualScroller のドキュメントをご覧ください。


<AutoComplete value={selectedItem} suggestions={filteredItems} completeMethod={searchItems}
    virtualScrollerOptions={{ itemSize: 38 }} field="label" dropdown onChange={(e) => setSelectedItem(e.value)} />

複数#

複数モードは、オートコンプリートから複数の値を選択するために使用される _multiple_ プロパティを使用して有効になります。この場合、値参照は配列である必要があります。選択可能な値の数は、 _selectionLimit_ プロパティを使用して制限できます。


<AutoComplete field="name" multiple value={selectedCountries} suggestions={filteredCountries} completeMethod={search} onChange={(e) => setSelectedCountries(e.value)} />

フローティングラベル#

フォーカスされると、入力フィールドの上にフローティングラベルが表示されます。

フローティングラベル


<span className="p-float-label">
    <AutoComplete inputId="ac" value={value} suggestions={items} completeMethod={search} onChange={(e) => setValue(e.value)} />
    <label htmlFor="ac">Float Label</label>
</span>

塗りつぶし#

コンポーネントをデフォルトの _outlined_ スタイルよりも高い視覚的強調で表示するには、_variant_ プロパティを _filled_ として指定します。


<AutoComplete value={value} suggestions={items} completeMethod={search} onChange={(e) => setValue(e.value)} variant="filled" />

無効#

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


<AutoComplete invalid={value.length < 1} value={value} suggestions={items} completeMethod={search} onChange={(e) => setValue(e.value)} />

無効#

_disabled_ が存在する場合、要素を編集したりフォーカスしたりすることはできません。


<AutoComplete disabled placeholder="Disabled" />

アクセシビリティ#

スクリーンリーダー

コンポーネントを記述する値は、_inputId_ プロパティと組み合わせて _label_ タグを介して提供することも、_aria-labelledby_、_aria-label_ プロパティを使用して提供することもできます。入力要素には、 _aria-autocomplete_、_aria-haspopup_、_aria-expanded_ 属性に加えて、_combobox_ ロールがあります。入力とポップアップの関係は _aria-controls_ で作成され、_aria-activedescendant_ 属性は、ポップアップリスト内でのキーボードナビゲーション中にどのオプションを読み取るかの指示にスクリーンリーダーによって使用されます。

複数モードでは、チップリストは _listbox_ ロールを使用し、_aria-orientation_ は水平に設定されます。一方、各チップは _option_ ロールを持ち、_aria-label_ はチップのラベルに設定されます。

ポップアップリストには、入力要素の _aria-controls_ 属性を参照する ID があり、ロールとして _listbox_ を使用します。各リストアイテムには _option_ ロールと、入力要素の _aria-activedescendant_ と一致する ID があります。


<label htmlFor="ac1">Username</label>
<AutoComplete inputId="ac1" />

<span id="ac2">Email</span>
<AutoComplete aria-labelledby="ac2" />

<AutoComplete aria-label="City" />

キーボードサポート

キー	機能
tab	ポップアップが表示されていない場合は、フォーカスを入力要素に移動します。ポップアップが開いていてアイテムが強調表示されている場合、ポップアップは閉じられ、アイテムが選択され、フォーカスは次のフォーカス可能な要素に移動します。
上矢印	ポップアップが表示されている場合は、前のアイテムを強調表示します.
下矢印	ポップアップが表示されている場合は、次のアイテムを強調表示します。
enter	強調表示されているアイテムを選択し、ポップアップが表示されている場合はポップアップを閉じます。
home	ポップアップが表示されている場合は、最初のアイテムを強調表示します。
end	ポップアップが表示されている場合は、最後のアイテムを強調表示します。
escape	ポップアップを非表示にします。

チップ入力キーボードサポート

キー	機能
backspace	入力フィールドが空の場合、前のチップを削除します。
左矢印	入力フィールドが空の場合、フォーカスを前のチップに移動します（利用可能な場合）。

チップキーボードサポート

キー	機能
左矢印	フォーカスを前のチップに移動します（利用可能な場合）。
右矢印キー	フォーカスを次のチップに移動します。チップがない場合は、入力フィールドにフォーカスが移動します。
backspace	チップを削除し、入力フィールドにフォーカスを追加します。