下拉列表

下拉列表，也称为选择框，用于从选项集合中选择一个项目。

导入#


import { Dropdown } from 'primereact/dropdown';

基本用法#

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


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

复选标记#

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


<Dropdown value={selectedCity} onChange={(e) => setSelectedCity(e.value)} options={cities} optionLabel="name" 
    placeholder="Select a City" className="w-full md:w-14rem" checkmark={true}  highlightOnSelect={false} />

可编辑#

当存在 editable 时，也可以通过键入来输入。


<Dropdown value={selectedCity} onChange={(e) => setSelectedCity(e.value)} options={cities} optionLabel="name" 
    editable placeholder="Select a City" className="w-full md:w-14rem" />

分组#

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


<Dropdown value={selectedCity} onChange={(e) => setSelectedCity(e.value)} options={groupedCities} optionLabel="label" 
    optionGroupLabel="label" optionGroupChildren="items" optionGroupTemplate={groupedItemTemplate} className="w-full md:w-14rem" placeholder="Select a City" />

模板#

选项和选定选项显示分别使用 itemTemplate 和 valueTemplate 属性支持模板。


<Dropdown value={selectedCountry} onChange={(e) => setSelectedCountry(e.value)} options={countries} optionLabel="name" placeholder="Select a Country" 
    valueTemplate={selectedCountryTemplate} itemTemplate={countryOptionTemplate} className="w-full md:w-14rem" panelFooterTemplate={panelFooterTemplate}
    dropdownIcon={(opts) => {
        return opts.iconProps['data-pr-overlay-visible'] ? <ChevronRightIcon {...opts.iconProps} /> : <ChevronDownIcon {...opts.iconProps} />;
    }} 
/>

筛选#

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


<Dropdown value={selectedCountry} onChange={(e) => setSelectedCountry(e.value)} options={countries} optionLabel="name" placeholder="Select a Country" 
    filter valueTemplate={selectedCountryTemplate} itemTemplate={countryOptionTemplate} className="w-full md:w-14rem" />

清除图标#

启用 showClear 后，会添加一个清除图标来重置下拉列表。


<Dropdown value={selectedCity} onChange={(e) => setSelectedCity(e.value)} options={cities} optionLabel="name" 
    showClear placeholder="Select a City" className="w-full md:w-14rem" />

加载状态#

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


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

虚拟滚动#

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


<Dropdown value={selectedItem} onChange={(e) => setSelectedItem(e.value)} options={items} virtualScrollerOptions={{ itemSize: 38 }} 
    placeholder="Select Item" className="w-full md:w-14rem" />

惰性虚拟滚动#


<Dropdown value={selectedItem} onChange={(e) => setSelectedItem(e.value)} options={items} virtualScrollerOptions={{ itemSize: 38 }} 
    placeholder="Select Item" className="w-full md:w-14rem" />

浮动标签#

当获得焦点时，浮动标签会出现在输入字段的顶部。

选择一个城市


<FloatLabel>
    <Dropdown inputId="dd-city" value={selectedCity} onChange={(e) => setSelectedCity(e.value)} options={cities} optionLabel="name" className="w-full" />
    <label htmlFor="dd-city">Select a City</label>
</FloatLabel>

填充#

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


<Dropdown variant="filled" value={selectedCity} onChange={(e) => setSelectedCity(e.value)} options={cities} optionLabel="name" 
    placeholder="Select a City" className="w-full md:w-14rem" />

无效#

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


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

禁用#

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


<Dropdown disabled placeholder="Select a City" className="w-full md:w-14rem" />

无障碍#

屏幕阅读器

用于描述组件的值可以使用 aria-labelledby 或 aria-label 属性提供。除了 aria-haspopup 和 aria-expanded 属性外，下拉列表元素还具有 combobox 角色。如果启用了可编辑选项，则还会添加 aria-autocomplete。使用 aria-controls 创建组合框和弹出窗口之间的关系，并且使用 aria-activedescendant 属性来指示屏幕阅读器在弹出列表中的键盘导航期间读取哪个选项。

弹出列表具有一个 ID，该 ID 引用 combobox 元素的 aria-controls 属性，并使用 listbox 作为角色。每个列表项都具有一个 option 角色，一个与 aria-activedescendant输入元素以及 aria-label、aria-selected 和 aria-disabled 属性匹配的 ID。

如果启用了筛选，则可以定义 filterInputProps，以便为筛选输入元素提供 aria-* 属性。


<span id="dd1">Options</span>
<Dropdown aria-labelledby="dd1" />

<Dropdown aria-label="Options" />

关闭状态键盘支持

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

弹出窗口键盘支持

按键	功能
tab	将焦点移动到弹出窗口中的下一个可聚焦元素，如果没有，则第一个可聚焦元素接收焦点。
shift + tab	将焦点移动到弹出窗口中的上一个可聚焦元素，如果没有，则最后一个可聚焦元素接收焦点。
回车	选择聚焦的选项并关闭弹出窗口。
空格	选择聚焦的选项并关闭弹出窗口。
Esc	关闭弹出窗口，将焦点移动到下拉列表元素。
向下箭头	将焦点移动到下一个选项，如果没有，则视觉焦点不更改。
向上箭头	将焦点移动到上一个选项，如果没有，则视觉焦点不更改。
向右箭头	如果下拉列表是可编辑的，则从当前选项中移除视觉焦点，并将输入光标向左移动一个字符。
向左箭头	如果下拉列表是可编辑的，则从当前选项中移除视觉焦点，并将输入光标向右移动一个字符。
Home	如果下拉列表是可编辑的，则将输入光标移动到末尾；如果不是，则将焦点移动到第一个选项。
End	如果下拉列表是可编辑的，则将输入光标移动到开头；如果不是，则将焦点移动到最后一个选项。
任何可打印字符	如果下拉列表不可编辑，则将焦点移动到标签以键入的字符开头的选项。

筛选输入键盘支持

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