选择

选择用于从选项集合中选择一项。


import Select from 'primevue/select';

选择与v-model属性一起用于双向值绑定以及options集合。选项的标签和值分别使用optionLabeloptionValue属性定义。 请注意,当选项是简单的原始值(例如字符串数组)时,不需要optionLabeloptionValue


<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 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>

选择提供尺寸作为基本尺寸的替代方案。


<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 prop 显示,以指示验证失败。 在与表单验证库集成时,可以使用此样式。


<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-labelledbyaria-label props 提供。 除了aria-haspopuparia-expanded属性外,select 元素还具有combobox角色。 如果启用了可编辑选项,还会添加aria-autocomplete。 combobox 和弹出窗口之间的关系是通过aria-controls创建的,并且aria-activedescendant属性用于指示屏幕阅读器在弹出列表中的键盘导航期间要读取哪个选项。

弹出列表的 ID 引用 combobox 元素的 aria-controls 属性,并使用 listbox 作为角色。每个列表项都有一个 option 角色,一个与输入元素的 aria-activedescendant 匹配的 ID,以及 aria-labelaria-selectedaria-disabled 属性。

如果启用了过滤,可以定义 filterInputProps 来为过滤输入元素提供 aria-* 属性。


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

<select aria-label="Options" />

关闭状态下的键盘支持

按键功能
tab将焦点移动到选择元素。
空格打开弹出窗口并将视觉焦点移动到选定的选项;如果没有选定的选项,则第一个选项获得焦点。
回车打开弹出窗口并将视觉焦点移动到选定的选项;如果没有选定的选项,则第一个选项获得焦点。
向下箭头打开弹出窗口并将视觉焦点移动到选定的选项;如果没有选定的选项,则第一个选项获得焦点。
向上箭头打开弹出窗口并将视觉焦点移动到选定的选项;如果没有选定的选项,则最后一个选项获得焦点。
任何可打印字符打开弹出窗口并将焦点移动到标签以输入的字符开头的选项;如果没有匹配的选项且选择框不可编辑,则第一个选项获得焦点。

弹出窗口的键盘支持

按键功能
tab将焦点移动到弹出窗口中的下一个可聚焦元素。如果没有,则选择可聚焦的选项并关闭覆盖层,然后将焦点移动到页面中的下一个元素。
shift + tab将焦点移动到弹出窗口中的上一个可聚焦元素。如果没有,则选择可聚焦的选项并关闭覆盖层,然后将焦点移动到页面中的下一个元素。
回车选择焦点所在的选项并关闭弹出窗口,然后将焦点移动到选择元素。
空格选择焦点所在的选项并关闭弹出窗口,然后将焦点移动到选择元素。
escape关闭弹出窗口,然后将焦点移动到选择元素。
向下箭头将焦点移动到下一个选项;如果没有下一个选项,则视觉焦点不改变。
向上箭头将焦点移动到上一个选项;如果没有上一个选项,则视觉焦点不改变。
alt + 向上箭头选择焦点所在的选项并关闭弹出窗口,然后将焦点移动到选择元素。
向左箭头如果选择框可编辑,则移除当前选项的视觉焦点并将输入光标向左移动一个字符。
向右箭头如果选择框可编辑,则移除当前选项的视觉焦点并将输入光标向右移动一个字符。
home如果选择框可编辑,则将输入光标移动到末尾;如果不可编辑,则将焦点移动到第一个选项。
end如果选择框可编辑,则将输入光标移动到开头;如果不可编辑,则将焦点移动到最后一个选项。
pageUp将视觉焦点跳转到第一个选项。
pageDown将视觉焦点跳转到最后一个选项。
任何可打印字符如果选择框不可编辑,则将焦点移动到标签以输入的字符开头的选项。

过滤输入框的键盘支持

按键功能
向下箭头将焦点移动到下一个选项;如果没有下一个选项,则视觉焦点不改变。
向上箭头将焦点移动到上一个选项;如果没有上一个选项,则视觉焦点不改变。
向左箭头移除当前选项的视觉焦点并将输入光标向左移动一个字符。
向右箭头移除当前选项的视觉焦点并将输入光标向右移动一个字符。
home将输入光标移动到末尾;如果不可编辑,则将焦点移动到第一个选项。
end将输入光标移动到开头;如果不可编辑,则将焦点移动到最后一个选项。
回车关闭弹出窗口并将焦点移动到选择元素。
escape关闭弹出窗口并将焦点移动到选择元素。
tab将焦点移动到弹出窗口中的下一个可聚焦元素。如果没有,则选择可聚焦的选项并关闭覆盖层,然后将焦点移动到页面中的下一个元素。