自動完成

自動完成是一個輸入元件，可在輸入時提供即時建議。

匯入 # 


import AutoComplete from 'primevue/autocomplete';

基本 #

自動完成使用 v-model 屬性進行雙向數值綁定。此外，還需要 suggestions 屬性和 complete 方法來查詢結果。

找不到結果

<AutoComplete v-model="value" :suggestions="items" @complete="search" />

物件 #

自動完成可以使用 optionLabel 屬性來處理物件，該屬性定義要顯示為建議的標籤。傳遞給模型的數值仍然是建議的物件實例。以下是一個使用 Country 物件的範例，該物件具有 name 和 code 欄位，例如 {name: "美國", code:"USA"}。

找不到結果

<AutoComplete v-model="selectedCountry" optionLabel="name" :suggestions="filteredCountries" @complete="search" />

表單 #

自動完成與 PrimeVue 表單 程式庫無縫整合。

找不到結果

<Form v-slot="$form" :resolver="resolver" :initialValues="initialValues" @submit="onFormSubmit" class="flex justify-center flex-col gap-4 w-full md:w-56">
    <div class="flex flex-col gap-1">
        <AutoComplete name="country" optionLabel="name" :suggestions="filteredCountries" @complete="search" />
        <Message v-if="$form.country?.invalid" severity="error" size="small" variant="simple">{{ $form.country.error?.message }}</Message>
    </div>
    <Button type="submit" severity="secondary" label="Submit" />
</Form>

下拉式選單 #

啟用 dropdown 屬性會在輸入欄位旁邊顯示一個按鈕，該按鈕的點擊行為是使用 dropdownMode 屬性定義的，該屬性可以採用 blank 或 current 作為可能的值。blank 是預設模式，會傳送空字串的查詢，而 current 設定則會傳送輸入的目前值的查詢。

找不到結果

<AutoComplete v-model="value" dropdown :suggestions="items" @complete="search" />

範本 #

自動完成提供多個插槽，可透過範本進行自訂。

找不到結果

<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>
    <template #header>
        <div class="font-medium px-3 py-2">Available Countries</div>
    </template>
    <template #footer>
        <div class="px-3 py-3">
            <Button label="Add New" fluid severity="secondary" text size="small" icon="pi pi-plus" />
        </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 以強制輸入始終來自建議清單。

找不到結果

<AutoComplete v-model="selectedCountry" forceSelection optionLabel="name" :suggestions="filteredCountries" @complete="search" />

虛擬捲動 #

虛擬捲動是一種高效能的方式來呈現大型清單。捲動行為的設定是使用 virtualScrollerOptions 定義的，這需要 itemSize 作為強制值來設定項目的高度。請造訪 虛擬捲動器 文件，以取得有關設定 API 的更多資訊。

找不到結果

<AutoComplete v-model="selectedItem" :suggestions="filteredItems" @complete="searchItems"
    :virtualScrollerOptions="{ itemSize: 38 }" optionLabel="label" dropdown />

填滿 #

指定 variant 屬性為 filled 以顯示具有比預設 outlined 樣式更高視覺強調的元件。

找不到結果

<AutoComplete v-model="value" :suggestions="items" @complete="search" variant="filled" />

浮動標籤 #

當輸入欄位取得焦點時，浮動標籤會出現在輸入欄位上方。請造訪 浮動標籤 文件，以取得更多資訊。

找不到結果
找不到結果
找不到結果

<FloatLabel>
    <AutoComplete v-model="value1" inputId="over_label" :suggestions="items" @complete="search" />
    <label for="over_label">Over Label</label>
</FloatLabel>

<FloatLabel variant="in">
    <AutoComplete v-model="value2" inputId="in_label" :suggestions="items" @complete="search" variant="filled" />
    <label for="in_label">In Label</label>
</FloatLabel>

<FloatLabel variant="on">
    <AutoComplete v-model="value3" inputId="on_label" :suggestions="items" @complete="search" />
    <label for="on_label">On Label</label>
</FloatLabel>

Ifta 標籤 #

IftaLabel 用於建立內嵌頂部對齊的標籤。請造訪 Ifta 標籤 文件，以取得更多資訊。

找不到結果

<IftaLabel>
    <AutoComplete v-model="value" inputId="ac" :suggestions="items" @complete="search" variant="filled" />
    <label for="ac">Identifier</label>
</IftaLabel>

尺寸 #

自動完成提供 small 和 large 尺寸作為基本尺寸的替代方案。

找不到結果
找不到結果
找不到結果

<AutoComplete v-model="value1" :suggestions="items" @complete="search" size="small" placeholder="Small" dropdown />
<AutoComplete v-model="value2" :suggestions="items" @complete="search" placeholder="Normal" dropdown />
<AutoComplete v-model="value3" :suggestions="items" @complete="search" size="large" placeholder="Large" 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" />

無效 #

無效狀態是使用 invalid 屬性顯示的，以表示驗證失敗。當與表單驗證程式庫整合時，可以使用此樣式。

找不到結果
找不到結果

<AutoComplete v-model="value1" :suggestions="items" @complete="search" :invalid="!value1" placeholder="Code" />
<AutoComplete v-model="value2" :suggestions="items" @complete="search" :invalid="!value2" variant="filled" placeholder="Code" />

已停用 #

當存在 disabled 時，元素無法編輯和取得焦點。

找不到結果

<AutoComplete disabled placeholder="Disabled" />

無障礙設計 #

螢幕閱讀器

用於描述元件的值可以透過 label 標籤結合 inputId 屬性提供，也可以使用 aria-labelledby、aria-label 屬性。輸入元素除了具有 aria-autocomplete、aria-haspopup 和 aria-expanded 屬性外，還具有 combobox 角色。輸入和彈出視窗之間的關係是使用 aria-controls 建立的，而 aria-activedescendant 屬性則用於指示螢幕閱讀器在彈出清單中進行鍵盤瀏覽時要讀取的選項。

在多重模式下，晶片清單使用 listbox 角色，aria-orientation 設定為水平，而每個晶片都具有 option 角色，aria-label 設定為晶片的標籤。

彈出清單具有一個 ID，該 ID 指向輸入元素的 aria-controls 屬性，並使用 listbox 作為角色。每個清單項目都具有 option 角色和一個 ID，以符合輸入元素的 aria-activedescendant。


<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 + 向上箭頭選取焦點選項並關閉彈出視窗，然後將焦點移至自動完成元素。
向左箭頭移除目前選項的視覺焦點，並將輸入游標向左移動一個字元。
向右箭頭移除目前選項的視覺焦點，並將輸入游標向右移動一個字元。
home將輸入游標移至結尾，如果沒有，則將焦點移至第一個選項。
end將輸入游標移至開頭，如果沒有，則將焦點移至最後一個選項。
pageUp將視覺焦點跳至第一個選項。
pageDown將視覺焦點跳至最後一個選項。

晶片輸入鍵盤支援

按鍵功能
退格鍵如果輸入欄位為空，則刪除前一個晶片。
向左箭頭如果輸入欄位為空，且有前一個晶片，則將焦點移至前一個晶片。

晶片鍵盤支援

按鍵功能
向左箭頭如果有前一個晶片，則將焦點移至前一個晶片。
向右箭頭將焦點移至下一個晶片，如果沒有下一個晶片，則輸入欄位會獲得焦點。
退格鍵刪除所有晶片，並將焦點放在輸入欄位。
PrimeVue 4.2.5 on Vue 3，由 PrimeTek 提供