多选

多选用于从集合中选择多个项目。

导入 # 


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来定义搜索算法。有效值是“contains”（默认值）、“startsWith”和“endsWith”。

选择城市

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

浮动标签 #

当焦点位于输入字段上时，浮动标签会出现在输入字段的顶部。有关更多信息，请访问浮动标签文档。

空
空
空

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

Ifta 标签 #

IftaLabel 用于创建内联顶部对齐的标签。请访问IftaLabel 文档了解更多信息。

空

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

尺寸 #

MultiSelect 提供了 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将焦点移动到多选元素。
空格键打开弹出窗口并将视觉焦点移动到选定的选项，如果没有选定的选项，则第一个选项接收焦点。
回车键打开弹出窗口并将视觉焦点移动到选定的选项，如果没有选定的选项，则第一个选项接收焦点。
向下箭头打开弹出窗口并将视觉焦点移动到选定的选项，如果没有选定的选项，则第一个选项接收焦点。
向上箭头打开弹出窗口并将视觉焦点移动到选定的选项，如果没有选定的选项，则第一个选项接收焦点。
任何可打印字符打开弹出窗口并将焦点移动到标签以键入字符开头的选项，如果没有，则第一个选项接收焦点。

弹出窗口键盘支持

按键功能
tab将焦点移动到弹出窗口中下一个可聚焦的元素，如果没有，则第一个可聚焦的元素接收焦点。
shift + tab将焦点移动到弹出窗口中上一个可聚焦的元素，如果没有，则最后一个可聚焦的元素接收焦点。
回车键切换焦点选项的选择状态，然后将焦点移动到多选元素。
空格键切换焦点选项的选择状态，然后将焦点移动到多选元素。
Esc 键关闭弹出窗口，并将焦点移动到多选元素。
向下箭头将焦点移动到下一个选项，如果没有，则视觉焦点不变。
向上箭头将焦点移动到上一个选项，如果没有，则视觉焦点不变。
alt + 向上箭头选择焦点选项并关闭弹出窗口，然后将焦点移动到多选元素。
shift + 向下箭头将焦点移动到下一个选项并切换选择状态。
shift + 向上箭头将焦点移动到上一个选项并切换选择状态。
shift + 空格键选择最近选择的选项和焦点选项之间的项目。
Home 键将焦点移动到第一个选项。
End 键将焦点移动到最后一个选项。
control + shift + Home 键选择焦点选项和直到第一个选项的所有选项。
control + shift + End 键选择焦点选项和直到最后一个选项的所有选项。
control + a选择所有选项。
Page Up 键将视觉焦点跳转到第一个选项。
Page Down 键将视觉焦点跳转到最后一个选项。
任何可打印字符将焦点移动到标签以键入字符开头的选项。

切换全部复选框键盘支持

按键功能
空格键切换选中状态。
Esc 键关闭弹出窗口，并将焦点移动到多选元素。

筛选输入框键盘支持

按键功能
向下箭头将焦点移动到下一个选项，如果没有，则视觉焦点不变。
向上箭头将焦点移动到上一个选项，如果没有，则视觉焦点不变。
向左箭头从当前选项移除视觉焦点，并将输入光标向左移动一个字符。
向右箭头从当前选项移除视觉焦点，并将输入光标向右移动一个字符。
Home 键将输入光标移动到末尾，如果不是，则将焦点移动到第一个选项。
End 键将输入光标移动到开头，如果不是，则将焦点移动到最后一个选项。
回车键关闭弹出窗口，并将焦点移动到多选元素。
Esc 键关闭弹出窗口，并将焦点移动到多选元素。
tab将焦点移动到弹出窗口中下一个可聚焦的元素。如果没有，则选中可聚焦的选项，关闭覆盖层，然后将焦点移动到页面中的下一个元素。
PrimeVue 4.2.5 on Vue 3 by PrimeTek