自动完成

自动完成是一个输入组件，它在输入时提供实时建议

导入#


import { AutoComplete } from 'primereact/autocomplete';
         

基本用法#

自动完成组件用作受控组件，具有 value 和 onChange 属性。此外，还需要 suggestions 和 completeMethod 来查询结果。


<AutoComplete value={value} suggestions={items} completeMethod={search} onChange={(e) => setValue(e.value)}  />
         

下拉列表#

启用 dropdown 属性会在输入字段旁边显示一个按钮，该按钮的单击行为使用 dropdownMode 属性定义，该属性采用 blank 或 current 作为可能的值。 blank 是使用空字符串发送查询的默认模式，而 current 设置使用输入的当前值发送查询。


<AutoComplete value={value} suggestions={items} completeMethod={search} onChange={(e) => setValue(e.value)} dropdown />
         

对象#

自动完成可以使用 field 属性处理对象，该属性定义要显示为建议的标签。传递给模型的值仍然是建议的对象实例。以下是一个具有名称和代码字段的 Country 对象的示例，例如 {name: "United States", code:"USA"}。


<AutoComplete field="name" value={selectedCountry} suggestions={filteredCountries} completeMethod={search} onChange={(e) => setSelectedCountry(e.value)} />
         

模板#

可以使用 itemTemplate 属性将自定义内容显示为选项，该属性引用一个以建议选项为参数并返回元素的函数。类似地，可以使用 selectedItemTemplate 属性，通过相同的方法自定义多选模式下的芯片。请注意，目前 selectedItemTemplate 仅在多选模式下可用。


<AutoComplete field="name" value={selectedCountry} suggestions={filteredCountries}  
    completeMethod={search} onChange={(e) => setSelectedCountry(e.value)} itemTemplate={itemTemplate} panelFooterTemplate={panelFooterTemplate} />
         

分组#

选项组使用 optionGroupLabel 和 optionGroupChildren 属性指定。


<AutoComplete value={selectedCity} onChange={(e) => setSelectedCity(e.value)} suggestions={filteredCities} completeMethod={search}
        field="label" optionGroupLabel="label" optionGroupChildren="items" optionGroupTemplate={groupedItemTemplate} placeholder="Hint: type 'a'" />
         

强制选择#

强制选择模式会验证手动输入以检查它是否也存在于建议列表中，如果不存在，则清除输入值以确保传递给模型的值始终是建议之一。只需启用 forceSelection 来强制输入始终来自建议列表。


<AutoComplete value={value} suggestions={items} completeMethod={search} onChange={(e) => setValue(e.value)} forceSelection />
         

虚拟滚动#

虚拟滚动是一种渲染大型列表的高效方法。滚动行为的配置通过 virtualScrollerOptions 定义，它需要 itemSize 作为强制值来设置项目的高度。有关配置 API 的更多信息，请访问 VirtualScroller 文档。


<AutoComplete value={selectedItem} suggestions={filteredItems} completeMethod={searchItems}
    virtualScrollerOptions={{ itemSize: 38 }} field="label" dropdown onChange={(e) => setSelectedItem(e.value)} />
         

多选#

使用 multiple 属性启用多选模式，用于从自动完成中选择多个值。在这种情况下，值引用应为数组。可以使用 selectionLimit 属性来限制可选择的值的数量。


<AutoComplete field="name" multiple value={selectedCountries} suggestions={filteredCountries} completeMethod={search} onChange={(e) => setSelectedCountries(e.value)} />
         

浮动标签#

浮动标签在聚焦时出现在输入字段的顶部。


<span className="p-float-label">
    <AutoComplete inputId="ac" value={value} suggestions={items} completeMethod={search} onChange={(e) => setValue(e.value)} />
    <label htmlFor="ac">Float Label</label>
</span>
         

填充#

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


<AutoComplete value={value} suggestions={items} completeMethod={search} onChange={(e) => setValue(e.value)} variant="filled" />
         

无效#

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


<AutoComplete invalid={value.length < 1} value={value} suggestions={items} completeMethod={search} onChange={(e) => setValue(e.value)} />
         

禁用#

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


<AutoComplete disabled placeholder="Disabled" />
         

可访问性#

屏幕阅读器

描述组件的值可以通过与 inputId 属性组合的 label 标签提供，也可以使用 aria-labelledby、aria-label 属性提供。输入元素除了具有 combobox 角色之外，还具有 aria-autocomplete、aria-haspopup 和 aria-expanded 属性。输入和弹出窗口之间的关系使用 aria-controls 创建，aria-activedescendant 属性用于指示屏幕阅读器在弹出列表中的键盘导航期间读取哪个选项。

在多选模式下，芯片列表使用 listbox 角色，aria-orientation 设置为水平，而每个芯片都具有 option 角色，并且 aria-label 设置为芯片的标签。

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


<label htmlFor="ac1">Username</label>
<AutoComplete inputId="ac1" />

<span id="ac2">Email</span>
<AutoComplete aria-labelledby="ac2" />

<AutoComplete aria-label="City" />
         

键盘支持

按键功能
Tab当弹出窗口不可见时，将焦点移动到输入元素。如果弹出窗口打开且突出显示了一个项目，则弹出窗口将关闭，选择该项目，并将焦点移动到下一个可聚焦的元素。
向上箭头如果弹出窗口可见，则突出显示上一个项目。
向下箭头如果弹出窗口可见，则突出显示下一个项目。
Enter如果弹出窗口可见，则选择突出显示的项目并关闭弹出窗口。
Home如果弹出窗口可见，则突出显示第一个项目。
End如果弹出窗口可见，则突出显示最后一个项目。
esc隐藏弹出窗口。

标签输入键盘支持

按键功能
退格键如果输入字段为空，则删除上一个标签。
左箭头如果可用且输入字段为空，则将焦点移动到上一个标签。

标签键盘支持

按键功能
左箭头如果可用，则将焦点移动到上一个标签。
右箭头将焦点移动到下一个标签，如果没有标签，则输入字段接收焦点。
退格键删除标签并将焦点添加到输入字段。
                              PrimeReact 10.9.1，由PrimeTek提供