AutoCompleteは、入力中にリアルタイムで候補を表示する入力コンポーネントです。
import AutoComplete from 'primevue/autocomplete';
AutoCompleteは、v-modelプロパティを使用して制御されたコンポーネントとして使用されます。さらに、suggestionsプロパティと、結果をクエリするためのcompleteメソッドが必要です。
<AutoComplete v-model="value" :suggestions="items" @complete="search" />
dropdownプロパティを有効にすると、入力フィールドの横にボタンが表示されます。ボタンのクリック動作は、dropdownModeプロパティを使用して定義されます。このプロパティには、blankまたはcurrentの値を指定できます。blankはデフォルトモードで、空の文字列でクエリを送信します。一方、current設定では、入力の現在の値でクエリを送信します。
<AutoComplete v-model="value" dropdown :suggestions="items" @complete="search" />
AutoCompleteは、候補として表示するラベルを定義するoptionLabelプロパティを使用して、オブジェクトを処理できます。モデルに渡される値は、候補のオブジェクトインスタンスのままです。例として、{name: "United States", code:"USA"}のような名前とコードフィールドを持つCountryオブジェクトがあります。
<AutoComplete v-model="selectedCountry" optionLabel="name" :suggestions="filteredCountries" @complete="search" />
アイテムテンプレートを使用すると、候補パネル内にカスタムコンテンツを表示できます。テンプレートに渡されるslotProps変数は、候補コレクション内のアイテムを表すitemプロパティを提供します。さらに、optiongroup、chip、header、footerスロットが提供され、カスタマイズの幅が広がります。
<AutoComplete v-model="selectedCountry" optionLabel="name" :suggestions="filteredCountries" @complete="search">
<template #option="slotProps">
<div class="flex items-center">
<img :alt="slotProps.option.name" src="https://primefaces.org/cdn/primevue/images/flag/flag_placeholder.png" :class="`flag flag-${slotProps.option.code.toLowerCase()} mr-2`" style="width: 18px" />
<div>{{ slotProps.option.name }}</div>
</div>
</template>
</AutoComplete>
オプショングループは、optionGroupLabelプロパティとoptionGroupChildrenプロパティで指定します。
<AutoComplete v-model="selectedCity" :suggestions="filteredCities" @complete="search" optionLabel="label" optionGroupLabel="label" optionGroupChildren="items" placeholder="Hint: type 'a'">
<template #optiongroup="slotProps">
<div class="flex items-center country-item">
<img :alt="slotProps.option.label" src="https://primefaces.org/cdn/primevue/images/flag/flag_placeholder.png" :class="`flag flag-${slotProps.option.code.toLowerCase()} mr-2`" style="width: 18px" />
<div>{{ slotProps.option.label }}</div>
</div>
</template>
</AutoComplete>
ForceSelectionモードは、手動入力も候補リストに存在するかどうかを検証します。存在しない場合、入力値はクリアされ、モデルに渡される値が常に候補のいずれかになるようにします。forceSelectionを有効にするだけで、入力が常に候補リストからのものになるように強制できます。
<AutoComplete v-model="selectedCountry" forceSelection optionLabel="name" :suggestions="filteredCountries" @complete="search" />
バーチャルスクロールは、大きなリストを効率的にレンダリングする方法です。スクロール動作の設定は、アイテムの高さを設定するための必須値であるitemSizeを必要とするvirtualScrollerOptionsで定義されます。設定APIの詳細については、バーチャルスクローラーのドキュメントを参照してください。
<AutoComplete v-model="selectedItem" :suggestions="filteredItems" @complete="searchItems"
:virtualScrollerOptions="{ itemSize: 38 }" optionLabel="label" dropdown />
複数モードは、オートコンプリートから複数の値を選択するために使用されるmultipleプロパティを使用して有効になります。この場合、値の参照は配列である必要があります。
<label for="multiple-ac-1" class="font-bold mb-2 block">With Typeahead</label>
<AutoComplete v-model="value1" inputId="multiple-ac-1" multiple fluid :suggestions="items" @complete="search" />
<label for="multiple-ac-2" class="font-bold mt-8 mb-2 block">Without Typeahead</label>
<AutoComplete v-model="value2" inputId="multiple-ac-2" multiple fluid @complete="search" :typeahead="false" />
フォーカスされたときに、入力フィールドの上にフローティングラベルが表示されます。詳細については、フローティングラベルのドキュメントを参照してください。
<FloatLabel>
<AutoComplete v-model="value" inputId="ac" :suggestions="items" @complete="search" />
<label for="ac">Float Label</label>
</FloatLabel>
デフォルトのoutlinedスタイルよりも視覚的な強調表示が高いコンポーネントを表示するには、variantプロパティをfilledとして指定します。
<AutoComplete v-model="value" :suggestions="items" @complete="search" variant="filled" />
invalidプロパティを使用して、無効状態が表示され、検証の失敗を示します。フォーム検証ライブラリと統合する際に、このスタイルを使用できます。
<AutoComplete v-model="value" :suggestions="items" @complete="search" :invalid="value === ''"/>
disabledが存在する場合、要素は編集およびフォーカスできません。
<AutoComplete disabled placeholder="Disabled" />
コンポーネントの説明は、inputIdプロパティと組み合わせてlabelタグを使用するか、aria-labelledby、aria-labelプロパティを使用して提供できます。入力要素は、aria-autocomplete、aria-haspopup、aria-expanded属性に加えて、comboboxロールを持っています。入力とポップアップ間の関係はaria-controlsで作成され、aria-activedescendant属性は、ポップアップリスト内のキーボードナビゲーション中にスクリーンリーダーにどのオプションを読み上げるかを指示するために使用されます。
複数モードでは、チップリストは水平方向に設定されたaria-orientationを持つlistboxロールを使用し、各チップはaria-labelがチップのラベルに設定されたoptionロールを持ちます。
ポップアップリストには、入力要素のaria-controls属性を参照するIDがあり、ロールとしてlistboxを使用します。各リストアイテムはoptionロールと、入力要素のaria-activedescendantと一致するIDを持ちます。
<label for="ac1">;Username</label>
<AutoComplete inputId="ac1" />
<span id="ac2">Email</span>
<AutoComplete aria-labelledby="ac2" />
<AutoComplete aria-label="City" />
| キー | 機能 |
|---|---|
| tab | オートコンプリート要素にフォーカスを移動します。 |
| 任意の印刷可能な文字 | ポップアップを開き、最初のオプションにフォーカスを移動します。 |
| キー | 機能 |
|---|---|
| tab | ポップアップ内の次のフォーカス可能な要素にフォーカスを移動します。存在しない場合、フォーカス可能なオプションが選択され、オーバーレイが閉じられ、ページ内の次の要素にフォーカスが移動します。 |
| shift + tab | ポップアップ内の前のフォーカス可能な要素にフォーカスを移動します。存在しない場合、フォーカス可能なオプションが選択され、オーバーレイが閉じられ、ページ内の次の要素にフォーカスが移動します。 |
| enter | フォーカスされたオプションを選択し、ポップアップを閉じ、オートコンプリート要素にフォーカスを移動します。 |
| space | フォーカスされたオプションを選択し、ポップアップを閉じ、オートコンプリート要素にフォーカスを移動します。 |
| escape | ポップアップを閉じ、オートコンプリート要素にフォーカスを移動します。 |
| 下矢印 | 次のオプションにフォーカスを移動します。存在しない場合、視覚的なフォーカスは変わりません。 |
| 上矢印 | 前のオプションにフォーカスを移動します。存在しない場合、視覚的なフォーカスは変わりません。 |
| alt + 上矢印 | フォーカスされたオプションを選択し、ポップアップを閉じ、オートコンプリート要素にフォーカスを移動します。 |
| 左矢印 | 現在のオプションからの視覚的なフォーカスを削除し、入力カーソルを1文字左に移動します。 |
| 右矢印 | 現在のオプションからの視覚的なフォーカスを削除し、入力カーソルを1文字右に移動します。 |
| home | 入力カーソルを末尾に移動します。そうでない場合は、最初のオプションにフォーカスを移動します。 |
| end | 入力カーソルを先頭に移動します。そうでない場合は、最後のオプションにフォーカスを移動します。 |
| pageUp | 視覚的なフォーカスを最初のオプションにジャンプします。 |
| pageDown | 視覚的なフォーカスを最後のオプションにジャンプします。 |
| キー | 機能 |
|---|---|
| backspace | 入力フィールドが空の場合、前のチップを削除します。 |
| 左矢印 | 入力フィールドが空の場合、利用可能な場合は前のチップにフォーカスを移動します。 |
| キー | 機能 |
|---|---|
| 左矢印 | 利用可能な場合は前のチップにフォーカスを移動します。 |
| 右矢印 | 次のチップにフォーカスを移動します。存在しない場合、入力フィールドがフォーカスを受け取ります。 |
| backspace | チップを削除し、入力フィールドにフォーカスを追加します。 |