多選

多選用於從集合中選擇多個項目。

導入 # 


import MultiSelect from 'primevue/multiselect';

基本 #

多選使用 v-model 屬性進行雙向值綁定，並結合 options 集合。選項的標籤和值分別使用 optionLabel 和 optionValue 屬性定義。請注意，當選項是簡單的原始值（例如字串陣列）時，則不需要 optionLabel 和 optionValue。

選擇城市

<MultiSelect v-model="selectedCities" :options="cities" optionLabel="name" filter placeholder="Select Cities"
    :maxSelectedLabels="3" class="w-full md:w-80" />

表單 #

選擇城市

<Form v-slot="$form" :resolver="resolver" :initialValues="initialValues" @submit="onFormSubmit" class="flex justify-center flex-col gap-4">
    <div class="flex flex-col gap-1">
        <MultiSelect name="city" :options="cities" optionLabel="name" filter placeholder="Select Cities" :maxSelectedLabels="3" class="w-full md:w-80" />
        <Message v-if="$form.city?.invalid" severity="error" size="small" variant="simple">{{ $form.city.error?.message }}</Message>
    </div>
    <Button type="submit" severity="secondary" label="Submit" />
</Form>

晶片 #

預設情況下，選取的值會顯示為逗號分隔的清單，將 display 設定為 chip 會將其顯示為晶片。

選擇城市

<MultiSelect v-model="selectedCities" display="chip" :options="cities" optionLabel="name" filter placeholder="Select Cities"
    :maxSelectedLabels="3" class="w-full md:w-80" />

群組 #

當提供巢狀資料結構時，可以將選項分組。若要定義群組的標籤，則需要 optionGroupLabel 屬性，並且還需要 optionGroupChildren 來定義參照群組子系的屬性。

選擇城市

<MultiSelect v-model="selectedCities" :options="groupedCities" optionLabel="label" filter optionGroupLabel="label" optionGroupChildren="items" display="chip" placeholder="Select Cities" class="w-full md:w-80">
    <template #optiongroup="slotProps">
        <div class="flex items-center">
            <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>
</MultiSelect>

範本 #

多選透過範本提供多個自訂插槽。

選擇國家

<MultiSelect v-model="selectedCountries" :options="countries" optionLabel="name" filter placeholder="Select Countries" display="chip" class="w-full md:w-80">
    <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 #dropdownicon>
        <i class="pi pi-map" />
    </template>
    <template #filtericon>
        <i class="pi pi-map-marker" />
    </template>
    <template #header>
        <div class="font-medium px-3 py-2">Available Countries</div>
    </template>
    <template #footer>
        <div class="p-3 flex justify-between">
            <Button label="Add New" severity="secondary" text size="small" icon="pi pi-plus" />
            <Button label="Remove All" severity="danger" text size="small" icon="pi pi-times" />
        </div>
    </template>
</MultiSelect>

篩選 #

篩選允許使用標頭上的輸入欄位搜尋清單中的項目。若要使用篩選，請啟用 filter 屬性。預設情況下，搜尋時會使用 optionLabel，而 filterFields 可用於自訂要使用的欄位。此外，filterMatchMode 可用於定義搜尋演算法。有效值為「包含」（預設）、「開始於」和「結束於」。

選擇城市

<MultiSelect v-model="selectedCities" :options="cities" filter optionLabel="name" placeholder="Select Cities"
    :maxSelectedLabels="3" class="w-full md:w-80" />

清除圖示 #

當啟用 showClear 時，會新增一個清除圖示來重設多選。

選擇城市

<MultiSelect v-model="selectedCities" :options="cities" optionLabel="name" filter placeholder="Select Cities"
    :maxSelectedLabels="3" class="w-full md:w-80" />

載入狀態 #

可以使用 loading 屬性來使用載入狀態。

載入中...

<MultiSelect placeholder="Loading..." loading class="w-full md:w-80"></MultiSelect>

虛擬捲軸 #

虛擬捲軸用於有效率地呈現長選項清單，例如此範例中的 10 萬筆記錄。設定是透過 virtualScrollerOptions 屬性完成的，請參閱虛擬捲軸以取得有關可用選項的詳細資訊，因為它由多選在內部使用。

選取項目

<MultiSelect v-model="selectedItems" :options="items" :maxSelectedLabels="3" :selectAll="selectAll" optionLabel="label" optionValue="value"
    @selectall-change="onSelectAllChange($event)" @change="onChange($event)" :virtualScrollerOptions="{ itemSize: 44 }" filter placeholder="Select Item" class="w-full md:w-80" />

已填滿 #

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

選擇城市

<MultiSelect v-model="selectedCities" variant="filled" :options="cities" optionLabel="name" filter placeholder="Select Cities"
    :maxSelectedLabels="3" class="w-full md:w-80" />

浮動標籤 #

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

empty
empty
empty

<FloatLabel class="w-full md:w-80">
    <MultiSelect id="over_label" v-model="value1" :options="cities" optionLabel="name" filter :maxSelectedLabels="3" class="w-full" />
    <label for="over_label">Over Label</label>
</FloatLabel>

<FloatLabel class="w-full md:w-80" variant="in">
    <MultiSelect id="in_label" v-model="value2" :options="cities" optionLabel="name" filter :maxSelectedLabels="3" class="w-full" variant="filled" />
    <label for="in_label">In Label</label>
</FloatLabel>

<FloatLabel class="w-full md:w-80" variant="on">
    <MultiSelect id="on_label" v-model="value3" :options="cities" optionLabel="name" filter :maxSelectedLabels="3" class="w-full" />
    <label for="on_label">On Label</label>
</FloatLabel>

內嵌標籤 #

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

空的

<IftaLabel>
    <MultiSelect v-model="selectedCities" inputId="ms_cities" :options="cities" optionLabel="name" filter :maxSelectedLabels="3" class="w-full" variant="filled" />
    <label for="ms_cities">Cities</label>
</IftaLabel>

尺寸 #

多選提供 small 和 large 尺寸作為基本尺寸的替代方案。

小型
正常
大型

<MultiSelect v-model="value1" :options="cities" optionLabel="name" :maxSelectedLabels="3" class="w-full md:w-80" size="small" placeholder="Small" />
<MultiSelect v-model="value2" :options="cities" optionLabel="name" :maxSelectedLabels="3" class="w-full md:w-80" placeholder="Normal" />
<MultiSelect v-model="value3" :options="cities" optionLabel="name" :maxSelectedLabels="3" class="w-full md:w-80" size="large" placeholder="Large" />

無效 #

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

選擇城市
選擇城市

<MultiSelect v-model="selectedCities1" :options="cities" optionLabel="name" filter placeholder="Select Cities" 
        :maxSelectedLabels="3" :invalid="selectedCities1?.length === 0" class="w-full md:w-80" />
<MultiSelect v-model="selectedCities2" :options="cities" optionLabel="name" filter placeholder="Select Cities" 
        :maxSelectedLabels="3" :invalid="selectedCities2?.length === 0" class="w-full md:w-80" variant="filled" />

已停用 #

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

選擇城市

<MultiSelect disabled placeholder="Select Cities" class="w-full md:w-80" />

協助工具 #

螢幕閱讀器

可以使用 aria-labelledby 或 aria-label 屬性來提供描述元件的值。多選元件除了具有 aria-haspopup 和 aria-expanded 屬性之外，還具有 combobox 角色。組合框和彈出視窗之間的關係是使用 aria-controls 屬性建立的，該屬性指向彈出列表框的 ID。

彈出列表框使用 listbox 作為角色，並啟用 aria-multiselectable。每個列表項目都具有 option 角色，以及 aria-label、aria-selected 和 aria-disabled 屬性。

標頭的核取方塊元件內部使用隱藏的原生核取方塊元素，該元素僅對螢幕閱讀器可見。要讀取的值是使用 locale API 的 aria 屬性的 selectAll 和 unselectAll 鍵定義的。

如果啟用篩選，則可以定義 filterInputProps 以將 aria-* 屬性賦予輸入元素。

關閉按鈕預設使用 locale API 的 aria 屬性的 close 鍵作為 aria-label，可以使用 closeButtonProps 覆寫此設定。


<span id="dd1"></span>Options</span>
<MultiSelect aria-labelledby="dd1" />

<MultiSelect aria-label="Options" />

關閉狀態的鍵盤支援

按鍵功能
tab將焦點移至多選元素。
space開啟彈出視窗並將視覺焦點移至選定的選項，如果沒有選定的選項，則第一個選項會取得焦點。
enter開啟彈出視窗並將視覺焦點移至選定的選項，如果沒有選定的選項，則第一個選項會取得焦點。
向下箭頭開啟彈出視窗並將視覺焦點移至選定的選項，如果沒有選定的選項，則第一個選項會取得焦點。
向上箭頭開啟彈出視窗並將視覺焦點移至選定的選項，如果沒有選定的選項，則第一個選項會取得焦點。
任何可列印的字元開啟彈出視窗並將焦點移至標籤以鍵入字元開頭的選項，如果沒有符合的選項，則第一個選項會取得焦點。

彈出視窗的鍵盤支援

按鍵功能
tab將焦點移至彈出視窗中的下一個可取得焦點的元素，如果沒有，則第一個可取得焦點的元素會取得焦點。
shift + tab將焦點移至彈出視窗中的上一個可取得焦點的元素，如果沒有，則最後一個可取得焦點的元素會取得焦點。
enter切換焦點選項的選取狀態，然後將焦點移至多選元素。
space切換焦點選項的選取狀態，然後將焦點移至多選元素。
escape關閉彈出視窗，將焦點移至多選元素。
向下箭頭將焦點移至下一個選項，如果沒有，則視覺焦點不會改變。
向上箭頭將焦點移至上一個選項，如果沒有，則視覺焦點不會改變。
alt + 向上箭頭選取焦點選項並關閉彈出視窗，然後將焦點移至多選元素。
shift + 向下箭頭將焦點移至下一個選項並切換選取狀態。
shift + 向上箭頭將焦點移至上一個選項並切換選取狀態。
shift + space選取最近選取的選項和焦點選項之間的所有項目。
home將焦點移至第一個選項。
end將焦點移至最後一個選項。
control + shift + home選取焦點選項和直到第一個選項的所有選項。
control + shift + end選取焦點選項和直到最後一個選項的所有選項。
control + a選取所有選項。
pageUp將視覺焦點跳至第一個選項。
pageDown將視覺焦點跳至最後一個選項。
任何可列印的字元將焦點移至標籤以鍵入字元開頭的選項。

切換全部核取方塊鍵盤支援

按鍵功能
space切換核取狀態。
escape關閉彈出視窗並將焦點移至多選元素。

篩選輸入鍵盤支援

按鍵功能
向下箭頭將焦點移至下一個選項，如果沒有，則視覺焦點不會改變。
向上箭頭將焦點移至上一個選項，如果沒有，則視覺焦點不會改變。
向左箭頭移除當前選項的視覺焦點，並將輸入游標向左移動一個字元。
向右箭頭移除當前選項的視覺焦點，並將輸入游標向右移動一個字元。
home將輸入游標移動到末尾，如果不是，則將焦點移至第一個選項。
end將輸入游標移動到開頭，如果不是，則將焦點移至最後一個選項。
enter關閉彈出視窗並將焦點移至多選元素。
escape關閉彈出視窗並將焦點移至多選元素。
tab將焦點移至彈出視窗中的下一個可取得焦點的元素。如果沒有，則選取可取得焦點的選項，關閉覆蓋層，然後將焦點移至頁面中的下一個元素。
PrimeVue 4.2.5 on Vue 3 by PrimeTek