列表框

列表框用于从项目列表中选择一个或多个值。

导入 # 


import Listbox from 'primevue/listbox';

基本 #

列表框与v-model属性一起使用，用于双向值绑定以及options集合。选项的标签和值分别使用optionLabel和optionValue属性定义。请注意，当选项是简单的原始值（例如字符串数组）时，则无需optionLabel和optionValue。

  • 纽约
  • 罗马
  • 伦敦
  • 伊斯坦布尔
  • 巴黎
未选择任何项目

<Listbox v-model="selectedCity" :options="cities" optionLabel="name" class="w-full md:w-56" />

表单 #

列表框与 PrimeVue 表单库无缝集成。

  • 纽约
  • 罗马
  • 伦敦
  • 伊斯坦布尔
  • 巴黎
已选择 1 个项目

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

复选标记 #

突出显示所选选项的另一种方法是显示复选标记。

  • 纽约
  • 罗马
  • 伦敦
  • 伊斯坦布尔
  • 巴黎
未选择任何项目

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

多选 #

列表框默认允许选择单个项目，启用multiple属性可以选择多个项目。当存在可选的metaKeySelection时，其行为会发生变化，即选择新项目需要存在 meta 键。

  • 纽约
  • 罗马
  • 伦敦
  • 伊斯坦布尔
  • 巴黎
未选择任何项目

<Listbox v-model="selectedCity" :options="cities" multiple optionLabel="name" class="w-full md:w-56" />

分组 #

当提供嵌套数据结构时，可以对选项进行分组。要定义组的标签，需要optionGroupLabel属性，并且还需要optionGroupChildren来定义引用组子项的属性。

  • 德国
  • 柏林
  • 法兰克福
  • 汉堡
  • 慕尼黑
  • 美国
  • 芝加哥
  • 洛杉矶
  • 纽约
  • 旧金山
  • 日本
  • 京都
  • 大阪
  • 东京
  • 横滨
未选择任何项目

<Listbox v-model="selectedCity" :options="groupedCities" optionLabel="label" optionGroupLabel="label" optionGroupChildren="items" class="w-full md:w-56" listStyle="max-height:250px">
    <template #optiongroup="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.label }}</div>
        </div>
    </template>
</Listbox>

筛选 #

列表框提供内置筛选功能，可以通过添加filter属性来启用。

有 5 个结果可用
  • 纽约
  • 罗马
  • 伦敦
  • 伊斯坦布尔
  • 巴黎
未选择任何项目

<Listbox v-model="selectedCity" :options="cities" filter optionLabel="name" class="w-full md:w-56" />

模板 #

使用option插槽显示选项的自定义内容，该插槽将选项作为参数。其他可用的模板部分包括filter和optionGroup。

  • Australia
    澳大利亚
  • Brazil
    巴西
  • China
    中国
  • Egypt
    埃及
  • France
    法国
  • Germany
    德国
  • India
    印度
  • Japan
    日本
  • Spain
    西班牙
  • United States
    美国
未选择任何项目

<Listbox v-model="selectedCountry" :options="countries" optionLabel="name" class="w-full md:w-56" listStyle="max-height:250px">
    <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>
</Listbox>

虚拟滚动 #

VirtualScroller 用于高效渲染长列表选项，例如本演示中的 10 万条记录。配置通过virtualScrollerOptions属性完成，有关可用选项的更多信息，请参阅 VirtualScroller，因为它在内部由列表框使用。

未选择任何项目

<Listbox v-model="selectedItem" :options="items" optionLabel="label" optionValue="value"
    :virtualScrollerOptions="{ itemSize: 38 }" class="w-full md:w-56" listStyle="height:250px" striped />

无效 #

无效状态使用invalid prop 显示，以指示验证失败。在与表单验证库集成时，可以使用此样式。

  • 纽约
  • 罗马
  • 伦敦
  • 伊斯坦布尔
  • 巴黎
未选择任何项目

<Listbox v-model="selectedCity" :options="cities" optionLabel="name" :invalid="selectedCity === null"  class="w-full md:w-56" />

禁用 #

当存在disabled时，该元素无法编辑和聚焦。

  • 纽约
  • 罗马
  • 伦敦
  • 伊斯坦布尔
  • 巴黎
未选择任何项目

<Listbox v-model="selectedCity" disabled :options="cities" optionLabel="name" class="w-full md:w-56" />

可访问性 #

屏幕阅读器

可以使用 aria-labelledby 或 aria-label prop 提供描述组件的值。列表元素具有 listbox 角色，并具有 aria-multiselectable 属性，当启用多选时，该属性设置为 true。每个列表项都具有 option 角色，并具有 aria-selected 和 aria-disabled 作为其属性。

如果启用了筛选，则可以定义 filterInputProps 以将 aria-* prop 赋予输入元素。或者，屏幕阅读器通常也会使用 filterPlaceholder。


<span id="lb"></span>Options</span>
<Listbox aria-labelledby="lb" />

<Listbox aria-label="City" />

键盘支持

按键功能
tab将焦点移动到第一个选定的选项，如果没有，则第一个选项会接收焦点。
上箭头将焦点移动到上一个选项。
下箭头将焦点移动到下一个选项。
回车切换聚焦选项的选中状态。
空格切换聚焦选项的选中状态。
home将焦点移动到第一个选项。
end将焦点移动到最后一个选项。
shift + 下箭头将焦点移动到下一个选项并切换选择状态。
shift + 上箭头将焦点移动到上一个选项并切换选择状态。
shift + 空格选择最近选择的选项和聚焦选项之间的项目。
control + shift + home选择聚焦的选项以及直到第一个选项的所有选项。
control + shift + end选择聚焦的选项以及直到最后一个选项的所有选项。
control + a选择所有选项。
pageUp将视觉焦点跳转到第一个选项。
pageDown将视觉焦点跳转到最后一个选项。
任何可打印字符将焦点移动到标签以键入的字符开头的选项。

筛选输入键盘支持

按键功能
下箭头将焦点移动到下一个选项，如果没有，则视觉焦点不会改变。
上箭头将焦点移动到上一个选项，如果没有，则视觉焦点不会改变。
左箭头从当前选项中移除视觉焦点，并将输入光标向左移动一个字符。
右箭头从当前选项中移除视觉焦点，并将输入光标向右移动一个字符。
home将输入光标移动到末尾，如果没有，则将焦点移动到第一个选项。
end将输入光标移动到开头，如果没有，则将焦点移动到最后一个选项。
回车关闭弹出窗口并将焦点移动到多选元素。
escape关闭弹出窗口并将焦点移动到多选元素。
tab将焦点移动到组件中下一个可聚焦的元素。如果没有，则将焦点移动到页面中的下一个元素。
PrimeVue 4.2.5 基于 Vue 3，由 PrimeTek 提供