列表框

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

导入#


import { ListBox } from 'primereact/listbox';

基本#

列表框用作受控组件，具有value和onChange属性以及options集合。选项的标签和值分别使用optionLabel和optionValue定义。属性分别定义。optionLabel的默认属性名称为label，optionValue的默认属性名称为value。如果省略optionValue并且该对象没有value属性，则该对象本身将成为选项的值。请注意，当选项是简单的原始值（例如字符串数组）时，不需要optionLabel和optionValue。


<ListBox value={selectedCity} onChange={(e) => setSelectedCity(e.value)} options={cities} optionLabel="name" className="w-full md:w-14rem" />

多选#

默认情况下，列表框允许选择单个项目，启用multiple属性可以选择多个项目。当存在可选的metaKeySelection时，行为会更改为选择新项目需要按下 meta 键。


<ListBox multiple value={selectedCities} onChange={(e) => setSelectedCities(e.value)} options={cities} optionLabel="name" className="w-full md:w-14rem" />

分组#

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


<ListBox value={selectedCity} onChange={(e) => setSelectedCity(e.value)} options={groupedCities} optionLabel="label" 
    optionGroupLabel="label" optionGroupChildren="items" optionGroupTemplate={groupTemplate} className="w-full md:w-14rem" listStyle={{ maxHeight: '250px' }} />

筛选#

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


<ListBox filter value={selectedCity} onChange={(e) => setSelectedCity(e.value)} options={cities} optionLabel="name" className="w-full md:w-14rem" />

模板#

选项的自定义内容使用itemTemplate属性显示，该属性将选项作为参数。其他可用的模板部分是filterTemplate和optionGroupTemplate。


<ListBox value={selectedCountry} onChange={(e) => setSelectedCountry(e.value)} options={countries} optionLabel="name" 
    itemTemplate={countryTemplate} className="w-full md:w-14rem" listStyle={{ maxHeight: '250px' }} />

虚拟滚动#

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


<ListBox value={selectedItem} onChange={(e) => setSelectedItem(e.value)} options={items} 
    virtualScrollerOptions={{ itemSize: 38 }} className="w-full md:w-14rem" listStyle={{ height: '250px' }} />

无效#

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


<ListBox invalid value={selectedCity} onChange={(e) => setSelectedCity(e.value)} options={cities} optionLabel="name" 
    className="w-full md:w-14rem" />

禁用#

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


<ListBox disabled options={cities} optionLabel="name" className="w-full md:w-14rem" />

无障碍访问#

屏幕阅读器

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

如果启用了筛选，则可以定义 filterInputProps 以向输入元素提供 aria-* 属性。或者，屏幕阅读器通常也会使用 filterPlaceholder。


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

<ListBox aria-label="City" />

键盘支持

按键	功能
tab	将焦点移动到第一个选定的选项，如果没有，则第一个选项接收焦点。
向上箭头	将焦点移动到上一个选项。
向下箭头	将焦点移动到下一个选项。
回车键	切换焦点选项的选定状态。
空格键	切换焦点选项的选定状态。
Home	将焦点移动到第一个选项。
End	将焦点移动到最后一个选项。
shift + 向下箭头	将焦点移动到下一个选项并切换选择状态。
shift + 向上箭头	将焦点移动到上一个选项并切换选择状态。
shift + 空格键	选择最近选定的选项和焦点选项之间的项目。
control + shift + Home	选择焦点选项和直到第一个选项的所有选项。
control + shift + End	选择焦点选项和直到最后一个选项的所有选项。
control + a	选择所有选项。