多选

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

导入#


import { MultiSelect } from 'primereact/multiselect';

基本#

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

选择城市


<MultiSelect value={selectedCities} onChange={(e) => setSelectedCities(e.value)} options={cities} optionLabel="name" 
    placeholder="Select Cities" maxSelectedLabels={3} className="w-full md:w-20rem" />

标签#

默认情况下，选定的值以逗号分隔的列表显示，将 display 设置为 chip 会将它们显示为标签。

选择城市


<MultiSelect value={selectedCities} onChange={(e) => setSelectedCities(e.value)} options={cities} optionLabel="name" display="chip"
    placeholder="Select Cities" maxSelectedLabels={3} className="w-full md:w-20rem" />

分组#

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

选择城市


<MultiSelect value={selectedCities} options={groupedCities} onChange={(e) => setSelectedCities(e.value)} optionLabel="label" 
    optionGroupLabel="label" optionGroupChildren="items" optionGroupTemplate={groupedItemTemplate}
    placeholder="Select Cities" display="chip" className="w-full md:w-20rem" />

模板#

可用选项和选定选项分别使用 itemTemplate 和 selectedItemTemplate 属性支持模板。此外，还可以对页眉、页脚和筛选部分进行模板化。

选择国家


<MultiSelect value={selectedCountries} options={countries} onChange={(e) => setSelectedCountries(e.value)} optionLabel="name" 
    placeholder="Select Countries" itemTemplate={countryTemplate} panelFooterTemplate={panelFooterTemplate} className="w-full md:w-20rem" display="chip" />

筛选#

多选组件提供内置筛选功能，可以通过添加 filter 属性启用。

选择城市


<MultiSelect value={selectedCities} onChange={(e) => setSelectedCities(e.value)} options={cities} optionLabel="name" 
    filter placeholder="Select Cities" maxSelectedLabels={3} className="w-full md:w-20rem" />

加载状态#

可以使用 loading 属性来设置加载状态。

加载中...


<MultiSelect loading placeholder="Loading..." className="w-full md:w-20rem" />

虚拟滚动#

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

选择项目


<MultiSelect
    value={selectedItems}
    options={items}
    onChange={(e) => {
        setSelectedItems(e.value);
        setSelectAll(e.value.length === items.length);
    }}
    selectAll={selectAll}
    onSelectAll={(e) => {
        setSelectedItems(e.checked ? [] : items.map((item) => item.value));
        setSelectAll(!e.checked);
    }}
    virtualScrollerOptions={{ itemSize: 43 }}
    maxSelectedLabels={3}
    placeholder="Select Items"
    className="w-full md:w-20rem"
/>

浮动标签#

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

空

多选


<FloatLabel>
    <MultiSelect value={selectedCities} onChange={(e) => setSelectedCities(e.value)} options={cities} optionLabel="name" maxSelectedLabels={3} className="w-full" />
    <label htmlFor="ms-cities">MultiSelect</label>
</FloatLabel>

填充#

将 variant 属性指定为 filled 可以显示具有比默认 outlined 样式更高的视觉强调的组件。

选择城市


<MultiSelect value={selectedCities} onChange={(e) => setSelectedCities(e.value)} options={cities} optionLabel="name" 
    placeholder="Select Cities" maxSelectedLabels={3} className="w-full md:w-20rem" />

无效#

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

选择城市


<MultiSelect invalid value={selectedCities} onChange={(e) => setSelectedCities(e.value)} options={cities} optionLabel="name" 
    placeholder="Select Cities" maxSelectedLabels={3} className="w-full md:w-20rem" />

禁用#

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

选择城市


<MultiSelect disabled placeholder="Select Cities" className="w-full md:w-20rem" />

可访问性#

屏幕阅读器

可以使用 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">Options</span>
<MultiSelect aria-labelledby="dd1" />

<MultiSelect aria-label="Options" />

关闭状态键盘支持

按键	功能
tab	将焦点移动到多选元素。
空格	打开弹出窗口，并将视觉焦点移动到选定的选项，如果没有选定的选项，则第一个选项接收焦点。
向下箭头	打开弹出窗口，并将视觉焦点移动到选定的选项，如果没有选定的选项，则第一个选项接收焦点。
向上箭头	打开弹出窗口，并将视觉焦点移动到选定的选项，如果没有选定的选项，则第一个选项接收焦点。

弹出窗口键盘支持

按键	功能
tab	将焦点移动到弹出窗口中的下一个可聚焦元素，如果没有可聚焦元素，则第一个可聚焦元素接收焦点。
shift + tab	将焦点移动到弹出窗口中的上一个可聚焦元素，如果没有可聚焦元素，则最后一个可聚焦元素接收焦点。
回车	切换焦点选项的选择状态。
空格	切换焦点选项的选择状态。
Esc	关闭弹出窗口，并将焦点移动到多选元素。
向下箭头	将焦点移动到下一个选项，如果没有下一个选项，则视觉焦点不会改变。
向上箭头	将焦点移动到上一个选项，如果没有上一个选项，则视觉焦点不会改变。
Home	将焦点移动到第一个选项。
End	将焦点移动到最后一个选项。
任何可打印字符	如果下拉列表不可编辑，则将焦点移动到标签以正在键入的字符开头的选项。

切换所有复选框键盘支持

按键	功能
空格	切换选中状态。
Esc	关闭弹出窗口。

筛选输入键盘支持

按键	功能
回车	关闭弹出窗口，并将焦点移动到多选元素。
Esc	关闭弹出窗口，并将焦点移动到多选元素。

关闭按钮键盘支持

按键	功能
回车	关闭弹出窗口，并将焦点移动到多选元素。
空格	关闭弹出窗口，并将焦点移动到多选元素。
Esc	关闭弹出窗口，并将焦点移动到多选元素。