PrimeVue Listbox 组件完全指南从基础单选到虚拟滚动与表单集成【免费下载链接】primevueNext Generation Vue UI Component Library项目地址: https://gitcode.com/GitHub_Trending/pr/primevueListbox列表框是 PrimeVue 组件库中用于从列表中选择一个或多个值的核心表单组件适用于城市选择、国家选择、权限配置等场景。本指南以 listbox 组件文档 为主体结合 Listbox 源码实现 深入剖析其选中机制、过滤算法、键盘交互与无障碍支持读完你将能够独立完成从简单列表到 10 万级数据虚拟滚动的完整实战。快速导入与基本使用PrimeVue 采用按需引入的方式组件位于primevue/listbox路径下import Listbox from primevue/listbox;Listbox 通过v-model实现双向绑定配合options集合渲染选项列表。选项的标签label与值value分别由optionLabel和optionValue属性定义Listbox v-modelselectedCity :optionscities optionLabelname classw-full md:w-56 /其中cities是对象数组const selectedCity ref(); const cities ref([ { name: New York, code: NY }, { name: Rome, code: RM }, { name: London, code: LDN }, { name: Istanbul, code: IST }, { name: Paris, code: PRS } ]);值得注意的一个实现细节是当options是字符串、数字等原始类型数组时无需指定optionLabel与optionValue。从源码可以看到getOptionLabel方法对原始类型做了直接返回处理Listbox.vue#L178-L183此时列表项本身既是标签也是值getOptionLabel(option) { return this.optionLabel ? resolveFieldData(option, this.optionLabel) : typeof option string || typeof option number || typeof option boolean ? option : null; }optionLabel与optionValue不仅支持属性名字符串还支持函数形式getter例如:optionLabel(data) data.name.toUpperCase()这为动态计算标签值提供了灵活性类型定义见 Listbox.d.ts#L281-L297。选中状态呈现高亮与 Checkmark 两种模式默认情况下Listbox 通过背景高亮p-listbox-option-selected类标识当前选中项。除了高亮之外你还可以通过checkmark属性在选中项左侧显示一个对勾图标配合:highlightOnSelectfalse可以完全用对勾替代高亮Listbox v-modelselectedCity :optionscities optionLabelname checkmark :highlightOnSelectfalse classw-full md:w-56 /从模板实现看checkmark模式下选中项渲染CheckIcon对勾未选中项渲染BlankIcon占位空白图标从而保证所有选项文字对齐Listbox.vue#L92-L95template v-ifcheckmark CheckIcon v-ifisSelected(option) :classcx(optionCheckIcon) v-bindptm(optionCheckIcon) / BlankIcon v-else :classcx(optionBlankIcon) v-bindptm(optionBlankIcon) / /template同时注意highlightOnSelect控制高亮类是否添加样式类p-listbox-option-selected的生成条件是instance.isSelected(option) props.highlightOnSelect见 ListboxStyle.js#L19-L26因此:highlightOnSelectfalse会移除高亮背景只保留对勾。禁用状态当需要让组件不可编辑、不可聚焦时使用disabled属性即可Listbox v-modelselectedCity disabled :optionscities optionLabelname classw-full md:w-56 /在源码中disabled同时作用于交互入口与语义标记点击选择方法onOptionSelect首先检查this.disabled || this.isOptionDisabled(option)命中则直接返回Listbox.vue#L312-L320根元素上会追加p-disabled类并通过:data-p-disabled暴露状态ListboxStyle.js#L5-L13列表的aria-disabled属性会同步为true供屏幕阅读器识别Listbox.vue#L60。此外还可以用optionDisabled属性按选项单独禁用它支持属性名或函数未定义时默认全部可用isOptionDisabled返回resolveFieldData(option, this.optionDisabled)无该属性时返回falseListbox.vue#L196-L198。内置过滤Filter开启过滤只需添加filter属性组件会在头部渲染一个搜索输入框Listbox v-modelselectedCity :optionscities filter optionLabelname classw-full md:w-56 /过滤匹配模式与过滤字段Listbox 的过滤逻辑由filterMatchMode定义默认值为contains包含匹配可选startsWith、contains、endsWith三种模式见 BaseListbox.vue#L32-L35底层调用FilterService的对应算法FilterService.js。默认只在optionLabel指定的字段上过滤如果选项结构复杂可用filterFields指定多个候选字段如[name, code]其默认值即为[optionLabel]Listbox.vue#L734-L736。filterLocale则用于控制过滤时的区域设置默认取宿主环境的当前 locale。过滤的源码实现visibleOptions计算属性在开启过滤时对平铺列表或分组列表分别处理Listbox.vue#L706-L726平铺列表FilterService.filter(this.options, this.searchFields, this.filterValue, this.filterMatchMode, this.filterLocale)分组列表先对每个组的items子数组过滤只保留仍有可见子项的组filteredChildren?.length才 push 进结果。无匹配结果时显示emptyFilterMessage默认 No results found可通过 PrimeVue locale 配置覆盖。这一行为有对应的单元测试佐证在 Listbox.spec.js#L51-L66 中输入 is 后 5 个城市只渲染出 Istanbul 1 项文档示例数据里还有 Istanbul 与 Paris 均含 is 不成立时以实际测试数据为准此处 options 为 5 个城市过滤 is 后剩 2 项分组过滤测试见 Listbox.spec.js#L68-L114输入 ch 后仅保留含 Munich、Chicago 的两个分组。与 PrimeVue Forms 库集成Listbox 与 PrimeVue Forms 表单库无缝集成。表单中为组件指定name通过Form的resolver校验解析器与initialValues完成校验与回填Form v-slot$form :resolverresolver :initialValuesinitialValues submitonFormSubmit classflex flex-col gap-4 w-full sm:w-56 div classflex flex-col gap-1 Listbox namecity :optionscities optionLabelname fluid / Message v-if$form.city?.invalid severityerror sizesmall variantsimple{{ $form.city.error?.message }}/Message /div Button typesubmit severitysecondary labelSubmit / /Form其中fluid让组件撑满父容器 100% 宽度Message根据表单状态展示错误信息。配套的 Composition API 脚本使用zodResolver定义校验规则import { ref } from vue; import { zodResolver } from primevue/forms/resolvers/zod; import { useToast } from primevue/usetoast; import { z } from zod; const toast useToast(); const initialValues ref({ city: { name: } }); const resolver ref(zodResolver( z.object({ city: z.union([ z.object({ name: z.string().min(1, City is required.) }), z.any().refine((val) false, { message: City is required. }) ]) }) )); const onFormSubmit ({ valid }) { if (valid) { toast.add({ severity: success, summary: Form is submitted., life: 3000 }); } };组件层面Listbox 继承自BaseEditableHolder通过writeValue写回表单值并触发change事件Listbox.vue#L694-L697因此无需额外适配即可参与 Forms 的值管理与校验链路。当校验失败时可通过invalid属性或表单自动注入的错误状态呈现无效样式根元素的data-p状态里会带上invalid标记见 Listbox.vue#L767-L772。分组选项Group当options是嵌套结构时可以用optionGroupLabel定义分组标签字段、用optionGroupChildren定义指向子选项数组的字段名Listbox v-modelselectedCity :optionsgroupedCities optionLabellabel optionGroupLabellabel optionGroupChildrenitems classw-full md:w-56 listStylemax-height:250px template #optiongroupslotProps div classflex items-center img :altslotProps.option.name srchttps://primefaces.org/cdn/primevue/images/flag/flag_placeholder.png :classflag flag-${slotProps.option.code.toLowerCase()} mr-2 stylewidth: 18px / div{{ slotProps.option.label }}/div /div /template /Listbox分组数据结构示例const groupedCities ref([ { label: Germany, code: DE, items: [ { label: Berlin, value: Berlin }, { label: Frankfurt, value: Frankfurt }, { label: Hamburg, value: Hamburg }, { label: Munich, value: Munich } ] }, { label: USA, code: US, items: [ { label: Chicago, value: Chicago }, { label: Los Angeles, value: Los Angeles }, { label: New York, value: New York }, { label: San Francisco, value: San Francisco } ] }, { label: Japan, code: JP, items: [ { label: Kyoto, value: Kyoto }, { label: Osaka, value: Osaka }, { label: Tokyo, value: Tokyo }, { label: Yokohama, value: Yokohama } ] } ]);从模板可以看出分组项通过isOptionGroup(option)判断并渲染为optionGroup元素同时提供#optiongroup插槽自定义分组头部内容Listbox.vue#L66-L69。在计算aria-posinset时源码会减去分组占位保证每个真实选项的序号连续Listbox.vue#L208-L210。无效状态Invalidinvalid属性用于展示校验失败样式可自由配合第三方表单校验库使用Listbox v-modelselectedCity :optionscities optionLabelname :invalidselectedCity null classw-full md:w-56 /其设计令牌为--p-listbox-invalid-border-color见下文设计令牌表样式通过根元素上的p-invalid类与data-p-invalid状态暴露ListboxStyle.js#L5-L13。多选模式Multiple默认单选设置multiple后即可选择多个值此时v-model绑定的是一个数组Listbox v-modelselectedCity :optionscities multiple optionLabelname classw-full md:w-56 /metaKeySelection 行为metaKeySelection默认false决定多选交互方式false单击即切换toggle每个选项的选择状态无需修饰键true必须按住metaKeyMac 的 Cmd 或 Windows 的 Ctrl才能选择/取消选项否则会退化为单选式替换在触屏设备上metaKeySelection会被自动关闭optionTouched置为true后走非 meta 分支见 Listbox.vue#L350、L376。单选与多选的选中判断都通过isSelected完成多选时用d_value.some(v isEquals(v, optionValue))单选时直接isEquals(d_value, optionValue)其中isEquals支持通过dataKey指定唯一标识字段做深度相等比较Listbox.vue#L550-L557。多选下的键盘范围选择多选模式下shift 方向键可进行连续范围选择onOptionSelectRange会从startRangeIndex到焦点项之间取出所有可见有效选项并整体更新模型Listbox.vue#L393-L407ctrl/⌘ A全选则直接由列表 keydown 处理器完成Listbox.vue#L295-L301。自定义选项模板Template通过#option插槽可以完全自定义选项内容插槽参数包含option、selected与indexListbox v-modelselectedCountry :optionscountries optionLabelname classw-full md:w-56 listStylemax-height:250px template #optionslotProps div classflex items-center img :altslotProps.option.name srchttps://primefaces.org/cdn/primevue/images/flag/flag_placeholder.png :classflag flag-${slotProps.option.code.toLowerCase()} mr-2 stylewidth: 18px / div{{ slotProps.option.name }}/div /div /template /Listbox除option外Listbox 还提供以下插槽插槽说明option自定义选项内容参数含option、selected、indexoptiongroup自定义分组头内容参数含option、indexheader自定义头部区域footer自定义底部区域empty无可用选项时的提示内容emptyfilter过滤无结果时的提示内容loader虚拟滚动加载更多时的内容filtericon自定义过滤输入框图标插槽分发逻辑集中在模板的v-for循环中选项内容{{ getOptionLabel(option) }}作为默认插槽内容传入option、selected、index三个参数Listbox.vue#L96。虚拟滚动Virtual Scroll10 万条数据不卡顿Listbox 内部集成了VirtualScroller通过virtualScrollerOptions开启并配置。以下示例渲染 10 万条记录配合striped条纹样式与固定高度Listbox v-modelselectedItem :optionsitems optionLabellabel optionValuevalue :virtualScrollerOptions{ itemSize: 38 } classw-full md:w-56 listStyleheight:250px striped /const selectedItem ref(); const items ref(Array.from({ length: 100000 }, (_, i) ({ label: Item #${i}, value: i })));关键机制可在 Listbox.vue#L46-L47 与 Listbox.vue#L764-L766 验证virtualScrollerOptions未设置时视为禁用虚拟滚动virtualScrollerDisabled为true此时容器max-height使用scrollHeight启用后虚拟滚动由VirtualScroller组件接管渲染通过content插槽只渲染可视区附近的选项选项的索引在虚拟滚动模式下通过getItemOptions映射到真实数据下标getOptionIndex键盘导航与scrollInView在虚拟滚动下会调用virtualScroller.scrollToIndex(index)保证焦点项滚入视野Listbox.vue#L676-L687。更完整的 VirtualScroller 配置项如itemSize、numToleratedItems、lazy等请参考 VirtualScroller 组件。此外listStyle用于给内部列表元素设置内联样式如max-height:250pxscrollHeight默认14rem则定义视口高度超过该高度出现滚动条。无障碍Accessibility与键盘支持ARIA 语义通过aria-labelledby或aria-label为组件提供可访问名称例如Listbox aria-labelledbylb /或Listbox aria-labelCity /列表元素带有listboxrole多选开启时自动设置aria-multiselectabletrueListbox.vue#L55-L58每个列表项是optionrole携带aria-selected、aria-disabled、aria-setsize、aria-posinset属性开启过滤时可用filterInputProps给输入框注入aria-*属性同时filterPlaceholder也会被屏幕阅读器读取组件内置隐藏的rolestatus区域aria-livepolite用于播报过滤结果数、选中项数、空结果等状态Listbox.vue#L42-L44、L113-L118焦点管理通过首尾两个隐藏的可聚焦元素hiddenFirstFocusableEl/hiddenLastFocusableEl实现 Tab 环Listbox.vue#L3-L13、L119-L129。列表键盘操作按键功能Tab聚焦第一个选中项若无选中项则聚焦第一个选项↑焦点移动到上一个选项↓焦点移动到下一个选项Enter/Space切换焦点项的选择状态Home焦点移到第一个选项End焦点移到最后一个选项Shift ↓焦点移到下一项并切换选择状态Shift ↑焦点移到上一项并切换选择状态Shift Space选中最近选中项与焦点项之间的所有项Ctrl/⌘ Shift Home选中焦点项至第一项之间的所有项Ctrl/⌘ Shift End选中焦点项至最后一项之间的所有项Ctrl/⌘ A全选PageUp/PageDown视觉焦点跳到第一项 / 最后一项任意可打印字符焦点跳到标签以输入字符开头的选项连续输入有 500ms 匹配窗口见 Listbox.vue#L632-L662过滤输入框键盘操作按键功能↓焦点移到下一选项无则不变↑焦点移到上一选项无则不变←/→移除当前选项的视觉焦点光标左右移动Home光标移到末尾若非末尾否则焦点移到第一项End光标移到开头若非开头否则焦点移到最后一项Enter关闭弹层并聚焦到多选元素Escape关闭弹层并聚焦到多选元素Tab移到组件内下一个可聚焦元素无则移到页面下一元素上述键盘分发逻辑与onListKeyDown/onFilterKeyDown两个处理器一一对应Listbox.vue#L251-L311、L412-L448。其他常用属性与事件属性速查核心名称类型默认值说明modelValueany-组件值v-modeloptionsany[]-可选项数组optionLabelstring | Function-选项标签字段或 getteroptionValuestring | Function-选项值字段或 getter缺省时取选项本身optionDisabledstring | Function-选项禁用字段或 getteroptionGroupLabelstring | Function-分组标签字段或 getteroptionGroupChildrenstring | Function-分组子项数组字段或 getterscrollHeightstring14rem视口高度超出出现滚动条listStylestring-内部列表元素内联样式invalidbooleanfalse无效状态样式disabledbooleanfalse禁用整个组件fluidbooleannull撑满容器 100% 宽度dataKeystring-选项唯一标识字段用于相等比较multiplebooleanfalse允许多选metaKeySelectionbooleanfalse多选时是否需要 metaKey 切换触屏自动关闭filterbooleanfalse显示过滤输入框filterPlaceholderstring-过滤框占位文本filterLocalestring-过滤区域设置默认宿主环境 localefilterMatchModestartsWith|contains|endsWithcontains过滤匹配算法filterFieldsstring[]-过滤字段默认[optionLabel]virtualScrollerOptionsany-虚拟滚动配置VirtualScroller 属性对象autoOptionFocusbooleanfalse聚焦时是否聚焦第一个可见/选中项selectOnFocusbooleanfalse聚焦即选中focusOnHoverbooleantrue悬停即聚焦highlightOnSelectbooleantrue选中是否添加高亮类checkmarkbooleanfalse选中项显示对勾stripedbooleanfalse隔行变色tabindexstring | number-Tab 键顺序filterIconstring-过滤框图标ariaLabel/ariaLabelledbystring-可访问名称unstyledbooleanfalse移除组件核心样式注文档表格中autoOptionFocus标注默认false但 BaseListbox.vue#L44-L47 中该属性默认值为true实际行为以源码默认值为准。事件事件回调参数说明change{ originalEvent, value }值变化时触发focusevent获得焦点blurevent失去焦点filter{ originalEvent, value, filterValue }过滤输入变化option-dblclick/item-dblclick{ originalEvent, value }选项双击见 Listbox.vue#L336-L345Pass Throughpt定制Listbox 支持 PrimeVue 的 Pass Through 体系将属性/样式透传到内部 DOM 元素名称说明root根元素header头部元素pcFilterContainer内部 IconField 组件pcFilter内部 InputText 组件pcFilterIconContainer内部 InputIcon 组件filterIcon过滤图标元素listContainer列表容器virtualScroller内部 VirtualScroller 组件list列表ul元素optionGroup分组元素option选项元素可基于selected/focused/disabled上下文动态返回optionCheckIcon/optionBlankIcon对勾 / 占位图标emptyMessage空消息元素hiddenFirstFocusableEl/hiddenLastFocusableEl首尾隐藏聚焦元素hiddenFilterResult/hiddenSelectedMessage隐藏状态播报区域hooks生命周期钩子管理其中option的 pt 支持上下文函数getPTOptions会注入{ selected, focused, disabled }上下文供条件样式使用Listbox.vue#L187-L195。完整类型定义见 Listbox.d.ts#L122-L204。主题定制CSS 类与设计令牌CSS 类类名说明p-listbox根元素p-listbox-header头部元素p-listbox-filter过滤输入框p-listbox-list-container列表容器p-listbox-list列表元素p-listbox-option-group分组元素p-listbox-option选项元素p-listbox-option-check-icon选中对勾图标p-listbox-option-blank-icon未选中占位图标p-listbox-empty-message空消息元素这些类名定义于 ListboxStyle.js并额外包含p-listbox-striped、p-disabled、p-listbox-fluid、p-invalid等状态修饰类。设计令牌Design Tokens组件样式基于设计令牌生成 CSS 变量可在主题中覆盖TokenCSS 变量说明listbox.background--p-listbox-background根背景色listbox.disabled.background--p-listbox-disabled-background禁用背景listbox.border.color--p-listbox-border-color边框色listbox.invalid.border.color--p-listbox-invalid-border-color无效边框色listbox.color/listbox.disabled.color--p-listbox-color/--p-listbox-disabled-color文字色 / 禁用文字色listbox.shadow/listbox.border.radius--p-listbox-shadow/--p-listbox-border-radius阴影 / 圆角listbox.transition.duration--p-listbox-transition-duration过渡时长listbox.list.padding/listbox.list.gap--p-listbox-list-padding/--p-listbox-list-gap列表内边距 / 间距listbox.list.header.padding--p-listbox-list-header-padding列表头内边距listbox.option.focus.background--p-listbox-option-focus-background选项聚焦背景listbox.option.selected.background--p-listbox-option-selected-background选中背景listbox.option.selected.focus.background--p-listbox-option-selected-focus-background选中且聚焦背景listbox.option.color/focus.color/selected.color/selected.focus.color对应--p-listbox-option-*变量选项各状态文字色listbox.option.padding/border.radius--p-listbox-option-padding/--p-listbox-option-border-radius选项内边距 / 圆角listbox.option.striped.background--p-listbox-option-striped-background条纹行背景listbox.option.group.background/color/font.weight/padding--p-listbox-option-group-*变量分组样式listbox.checkmark.color/gutter.start/gutter.end--p-listbox-checkmark-*变量对勾颜色与沟槽listbox.empty.message.padding--p-listbox-empty-message-padding空消息内边距总结PrimeVue Listbox 是一个功能完备、开箱即用的选择组件通过v-modeloptionsoptionLabel三步即可完成基础列表filter、multiple、checkmark、分组与虚拟滚动覆盖了从几十条到 10 万条数据的各类场景而 ARIA 语义、完整键盘操作、Pass Through 定制与设计令牌体系则让它在可访问性、可定制性和主题一致性上达到组件库级水准。结合本仓库的 Listbox.vue 源码与 Listbox.spec.js 测试用例你可以进一步验证各属性的实际行为或参考 Listbox 官方文档 查看更多示例。【免费下载链接】primevueNext Generation Vue UI Component Library项目地址: https://gitcode.com/GitHub_Trending/pr/primevue创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
