選擇

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

導入 # 


import Select from 'primevue/select';

基本 #

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


<Select v-model="selectedCity" :options="cities" optionLabel="name" placeholder="Select a City" class="w-full md:w-56" />

表單 # 


<Form v-slot="$form" :resolver="resolver" :initialValues="initialValues" @submit="onFormSubmit" class="flex flex-col gap-4 w-full md:w-56">
    <div class="flex flex-col gap-1">
        <Select name="city" :options="cities" optionLabel="name" placeholder="Select a City" fluid />
        <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>

勾號 #

另一種強調選定選項的方式是顯示一個勾號。


<Select v-model="selectedCity" :options="cities" optionLabel="name" placeholder="Select a City" checkmark :highlightOnSelect="false" class="w-full md:w-56" />

可編輯 #

當存在editable時，也可以透過輸入文字來輸入。


<Select v-model="selectedCity" editable :options="cities" optionLabel="name" placeholder="Select a City" class="w-full md:w-56" />

群組 #

當提供巢狀資料結構時，可以對選項進行分組。要定義群組的標籤，需要optionGroupLabel屬性，並且還需要optionGroupChildren來定義指向群組子元素的屬性。


<Select v-model="selectedCity" :options="groupedCities" optionLabel="label" optionGroupLabel="label" optionGroupChildren="items" placeholder="Select a City" class="w-full md:w-56">
    <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="`mr-2 flag flag-${slotProps.option.code.toLowerCase()}`" style="width: 18px" />
            <div>{{ slotProps.option.label }}</div>
        </div>
    </template>
</Select>

範本 #

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


<Select v-model="selectedCountry" :options="countries" optionLabel="name" placeholder="Select a Country" class="w-full md:w-56">
    <template #value="slotProps">
        <div v-if="slotProps.value" class="flex items-center">
            <img :alt="slotProps.value.label" src="https://primefaces.org/cdn/primevue/images/flag/flag_placeholder.png" :class="`mr-2 flag flag-${slotProps.value.code.toLowerCase()}`" style="width: 18px" />
            <div>{{ slotProps.value.name }}</div>
        </div>
        <span v-else>
            {{ slotProps.placeholder }}
        </span>
    </template>
    <template #option="slotProps">
        <div class="flex items-center">
            <img :alt="slotProps.option.label" src="https://primefaces.org/cdn/primevue/images/flag/flag_placeholder.png" :class="`mr-2 flag flag-${slotProps.option.code.toLowerCase()}`" style="width: 18px" />
            <div>{{ slotProps.option.name }}</div>
        </div>
    </template>
    <template #dropdownicon>
        <i class="pi pi-map" />
    </template>
    <template #header>
        <div class="font-medium p-3">Available Countries</div>
    </template>
    <template #footer>
        <div class="p-3">
            <Button label="Add New" fluid severity="secondary" text size="small" icon="pi pi-plus" />
        </div>
    </template>
</Select>

篩選 #

選擇提供內建篩選功能，可以透過新增filter屬性來啟用。


<Select v-model="selectedCountry" :options="countries" filter optionLabel="name" placeholder="Select a Country" class="w-full md:w-56">
    <template #value="slotProps">
        <div v-if="slotProps.value" class="flex items-center">
            <img :alt="slotProps.value.label" src="https://primefaces.org/cdn/primevue/images/flag/flag_placeholder.png" :class="`mr-2 flag flag-${slotProps.value.code.toLowerCase()}`" style="width: 18px" />
            <div>{{ slotProps.value.name }}</div>
        </div>
        <span v-else>
            {{ slotProps.placeholder }}
        </span>
    </template>
    <template #option="slotProps">
        <div class="flex items-center">
            <img :alt="slotProps.option.label" src="https://primefaces.org/cdn/primevue/images/flag/flag_placeholder.png" :class="`mr-2 flag flag-${slotProps.option.code.toLowerCase()}`" style="width: 18px" />
            <div>{{ slotProps.option.name }}</div>
        </div>
    </template>
</Select>

清除圖示 #

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


<Select v-model="selectedCity" :options="cities" showClear optionLabel="name" placeholder="Select a City" class="w-full md:w-56" />

載入狀態 #

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


<Select placeholder="Loading..." loading class="w-full md:w-56"></Select>

虛擬捲動 #

VirtualScroller 用於有效地呈現長選項列表，例如此範例中的 10 萬筆記錄。組態使用 virtualScrollerOptions 屬性完成，有關可用選項的更多資訊，請參閱VirtualScroller，因為它由 Select 內部使用。


<Select v-model="selectedItem" :options="items" optionLabel="label" optionValue="value"
    :virtualScrollerOptions="{ itemSize: 38 }" placeholder="Select Item" class="w-full md:w-56" />

延遲虛擬捲動 # 


<Select v-model="selectedItem" :options="items" optionLabel="label" optionValue="value" class="w-full md:w-56"
    :virtualScrollerOptions="{ lazy: true, onLazyLoad: onLazyLoad, itemSize: 38, showLoader: true, loading: loading, delay: 250 }" placeholder="Select Item" />

已填滿 #

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


<Select v-model="selectedCity" variant="filled" :options="cities" optionLabel="name" placeholder="Select a City" class="w-full md:w-56" />

浮動標籤 #

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


<FloatLabel class="w-full md:w-56">
    <Select v-model="value1" inputId="over_label" :options="cities" optionLabel="name" class="w-full" />
    <label for="over_label">Over Label</label>
</FloatLabel>

<FloatLabel class="w-full md:w-56" variant="in">
    <Select v-model="value2" inputId="in_label" :options="cities" optionLabel="name" class="w-full" variant="filled" />
    <label for="in_label">In Label</label>
</FloatLabel>

<FloatLabel class="w-full md:w-56" variant="on">
    <Select v-model="value3" inputId="on_label" :options="cities" optionLabel="name" class="w-full" />
    <label for="on_label">On Label</label>
</FloatLabel>

內嵌標籤 #

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


<IftaLabel>
    <Select v-model="selectedCity" inputId="dd-city" :options="cities" optionLabel="name" class="w-full" variant="filled" />
    <label for="dd-city">City</label>
</IftaLabel>

尺寸 #

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


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

無效 #

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


<Select v-model="selectedCity1" :options="cities" optionLabel="name" placeholder="Select a City" :invalid="!selectedCity1" class="w-full md:w-56" />
<Select v-model="selectedCity2" :options="cities" optionLabel="name" placeholder="Select a City" :invalid="!selectedCity2" class="w-full md:w-56" variant="filled" />

已停用 #

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


<Select disabled placeholder="Select a City" class="w-full md:w-56" />

協助工具 #

螢幕閱讀器

描述元件的值可以使用 aria-labelledby 或 aria-label 屬性提供。除了 aria-haspopup 和 aria-expanded 屬性之外，select 元素還具有 combobox 角色。如果啟用可編輯選項，也會新增 aria-autocomplete。combobox 和彈出視窗之間的關聯是使用 aria-controls 建立的，並且 aria-activedescendant 屬性用於指示螢幕閱讀器在彈出列表中的鍵盤導覽期間應讀取的選項。

彈出式列表具有一個 id，該 id 指向 combobox 元素的 aria-controls 屬性，並使用 listbox 作為角色。每個列表項目都有一個 option 角色、一個與輸入元素的 aria-activedescendant 相符的 id，以及 aria-label、aria-selected 和 aria-disabled 屬性。

如果啟用篩選，則可以定義 filterInputProps，以便為篩選輸入元素提供 aria-* 屬性。


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

<select aria-label="Options" />

關閉狀態的鍵盤支援

按鍵功能
tab 鍵將焦點移動到選擇元素。
空白鍵開啟彈出視窗，並將視覺焦點移動到選定的選項。如果沒有選定的選項，則第一個選項會獲得焦點。
Enter 鍵開啟彈出視窗，並將視覺焦點移動到選定的選項。如果沒有選定的選項，則第一個選項會獲得焦點。
向下箭頭鍵開啟彈出視窗，並將視覺焦點移動到選定的選項。如果沒有選定的選項，則第一個選項會獲得焦點。
向上箭頭鍵開啟彈出視窗，並將視覺焦點移動到選定的選項。如果沒有選定的選項，則最後一個選項會獲得焦點。
任何可列印的字元開啟彈出視窗，並將焦點移動到標籤以輸入的字元開頭的選項。如果沒有這樣的選項且選擇欄位不可編輯，則第一個選項會獲得焦點。

彈出視窗鍵盤支援

按鍵功能
tab 鍵將焦點移動到彈出視窗中下一個可聚焦的元素。如果沒有，則會選取可聚焦的選項並關閉覆蓋層，然後將焦點移動到頁面中的下一個元素。
Shift + tab 鍵將焦點移動到彈出視窗中上一個可聚焦的元素。如果沒有，則會選取可聚焦的選項並關閉覆蓋層，然後將焦點移動到頁面中的下一個元素。
Enter 鍵選取已聚焦的選項並關閉彈出視窗，然後將焦點移動到選擇元素。
空白鍵選取已聚焦的選項並關閉彈出視窗，然後將焦點移動到選擇元素。
Escape 鍵關閉彈出視窗，然後將焦點移動到選擇元素。
向下箭頭鍵將焦點移動到下一個選項，如果沒有，則視覺焦點不會改變。
向上箭頭鍵將焦點移動到上一個選項，如果沒有，則視覺焦點不會改變。
Alt + 向上箭頭鍵選取已聚焦的選項並關閉彈出視窗，然後將焦點移動到選擇元素。
向左箭頭鍵如果選擇欄位可編輯，則會移除目前選項的視覺焦點，並將輸入游標向左移動一個字元。
向右箭頭鍵如果選擇欄位可編輯，則會移除目前選項的視覺焦點，並將輸入游標向右移動一個字元。
Home 鍵如果選擇欄位可編輯，則將輸入游標移動到末尾；如果不可編輯，則將焦點移動到第一個選項。
End 鍵如果選擇欄位可編輯，則將輸入游標移動到開頭；如果不可編輯，則將焦點移動到最後一個選項。
PageUp 鍵將視覺焦點跳轉到第一個選項。
PageDown 鍵將視覺焦點跳轉到最後一個選項。
任何可列印的字元如果選擇欄位不可編輯，則將焦點移動到標籤以輸入的字元開頭的選項。

篩選輸入鍵盤支援

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