自动完成

自动完成结合了文本输入框和列表框，允许用户根据查询过滤选项列表，找到匹配的项目。

安装

上述命令仅用于单独安装。如果 @heroui/react 已全局安装，则可以跳过此步骤。

导入

HeroUI 导出了 3 个与自动完成相关的组件

• Autocomplete：主组件，是其他组件的包装器。
• AutocompleteSection：包含一组自动完成项的组件。
• AutocompleteItem：表示一个自动完成项的组件。

用法

动态项目

Autocomplete 遵循 Collection Components API，接受静态和动态集合。

• 静态：上面的用法示例展示了静态实现，当选项的完整列表预先已知时可以使用。
• 动态：下面的示例可以在选项来自外部数据源（如 API 调用）或随时间更新时使用。

禁用

禁用项

您可以使用 disabledKeys 属性禁用特定项。

必填

如果您将 isRequired 属性传递给 autocomplete 组件，它将在标签末尾显示一个 danger 星号，并且该 autocomplete 将变为必填项。

只读

如果您将 isReadOnly 属性传递给 Autocomplete 组件，Listbox 将会打开以显示所有可用选项，但用户将无法选择任何列出的选项。

尺寸

颜色

变体

标签位置

您可以通过设置 labelPlacement 属性为 inside、outside 或 outside-left 来更改标签的位置。

注意：如果未传递 label，则 labelPlacement 属性将默认为 outside。

起始内容

您可以使用 startContent 和 endContent 属性向自动完成组件的开始和结尾添加内容。

条目起始和结束内容

由于 Autocomplete 组件在底层使用了 Listbox 组件，因此您可以使用 AutocompleteItem 组件的 startContent 和 endContent 属性，向自动完成条目的开始和结尾添加内容。

自定义值

默认情况下，Autocomplete 不允许用户指定列表中不存在的值，并且在失焦时会将输入值恢复为当前选定的值。通过指定 allowsCustomValue，此行为将被抑制，用户可以自由地在字段中输入任何值。

自定义选择器图标

默认情况下，Autocomplete 使用 chevron-down 图标作为选择器图标，该图标在自动完成组件打开时旋转。您可以通过将自定义图标传递给 selectorIcon 属性来自定义此图标。

注意：使用 disableSelectorIconRotation 属性禁用图标的旋转。

无滚动阴影

Autocomplete 组件在底层使用了 ScrollShadow，以便在自动完成内容可滚动时显示阴影。您可以通过使用 scrollShadowProps 属性来禁用此阴影。

注意：您还可以使用 showScrollIndicators 属性来禁用滚动指示器。

带有描述

您可以通过传递 description 属性向自动完成组件添加描述。

带有错误消息

您可以结合使用 isInvalid 和 errorMessage 属性来显示无效的自动完成组件。

事件

Autocomplete 组件支持通过鼠标、键盘和触摸进行选择。您可以通过 onSelectionChange 属性处理所有这些操作。Autocomplete 将把选定的键传递给 onSelectionChange 处理程序。此外，ComboBox 接受一个 onInputChange 属性，每当用户通过键入或选项选择编辑值时，都会触发该属性。

下面的示例使用 onSelectionChange 和 onInputChange 来更新存储在 React 状态中的选择和输入值。

受控

您可以使用 selectedKey 和 onSelectionChange 属性来控制选择的值。

完全受控

通过将 inputValue、selectedKey 和 items 传递给 Autocomplete，您可以精确控制 Autocomplete 应显示的内容。

以下示例展示了如何创建一个完全受控的 Autocomplete，从选定值 selectedKey 到组合框选项 items，所有内容都由您控制。

我们建议使用来自 @react-aria/i18n 的 useFilter Hook 来管理条目的过滤。

注意：重要的是要注意，您不必控制 Autocomplete 的每个方面。如果您决定仅控制 Autocomplete 的单个属性，请务必为该属性提供更改处理程序，例如，控制 selectedKey 将需要 onSelectionChange。

自定义条目

您可以通过修改 AutocompleteItem 子组件来自定义自动完成条目。

自定义空内容消息

默认情况下，如果没有结果与您的过滤器匹配，将显示消息 No results found.。您可以通过修改 listboxProps 中的 emptyContent 来自定义空内容消息。

自定义过滤

默认情况下，Autocomplete 使用来自 useFilter 的 "contains" 函数来过滤选项列表。这可以使用 defaultFilter 属性覆盖，或者通过使用 items 属性来控制过滤后的列表。当提供 items 而不是 defaultItems 时，Autocomplete 不会自行进行过滤。

以下示例使用 defaultFilter 属性使用自定义过滤器函数来过滤选项列表。

异步过滤

Autocomplete 支持异步过滤，在下面的示例中，我们使用来自 useAsyncList 函数和来自 react-aria 来处理来自服务器的异步加载和数据过滤。

异步加载

Autocomplete 支持异步加载，在下面的示例中，我们使用自定义 Hook 获取 Pokemon API 数据，并结合 useInfiniteScroll Hook，以便在用户到达列表末尾时加载更多数据。

当正在获取数据时，isLoading 属性用于显示加载指示器而不是选择器图标。

虚拟化

Autocomplete 支持虚拟化，在下面的示例中，我们使用 isVirtualized 属性来启用虚拟化。

注意：虚拟化策略基于 @tanstack/react-virtual 包，该包通过仅渲染视口中可见的条目来提供大型列表的高效渲染。

一万个条目

具有 10,000 个条目的虚拟化。

最大 Listbox 高度

maxListboxHeight 属性用于设置列表框的最大高度。当使用虚拟化时，这是必需的。默认情况下，它设置为 256。

自定义条目高度

itemHeight 属性用于设置列表框中每个条目的高度。当使用虚拟化时，这是必需的。默认情况下，它设置为 32。

带有节

您可以使用 AutocompleteSection 组件对自动完成条目进行分组。

自定义节样式

您可以使用 AutocompleteSection 组件的 classNames 属性来自定义节样式。

自定义自动完成组件

您可以使用 classNames 属性自定义自动完成组件的任何插槽。Autocomplete 组件还提供了 popoverProps、listboxProps、inputProps 属性，用于自定义 popover、listbox 和 input 组件。

插槽

• base：自动完成组件的主包装器。它包裹了 input 和 popover 组件。
• listboxWrapper：列表框的包装器。它包裹了 listbox 组件，此插槽在滚动阴影组件之上使用。
• listbox: listbox 组件。这是包裹自动完成项目的组件。
• popoverContent: popover 内容插槽。使用此项修改 popover 内容样式。
• endContentWrapper: 结尾内容（end content）的包装器。这会包裹清除按钮和选择器按钮。
• clearButton: 清除按钮插槽。
• selectorButton: 选择器按钮插槽。

数据属性

Autocomplete 在 base 元素上具有以下属性

• data-invalid: 当自动完成组件无效时。基于 isInvalid prop。
• data-open: 指示自动完成组件的 popover 是否打开。

Autocomplete 在 selectorButton 元素上具有以下属性

• data-open: 指示自动完成组件的 popover 是否打开。

Autocomplete 在 clearButton 元素上具有以下属性

• data-visible: 指示自动完成组件的清除按钮是否可见。默认情况下，当鼠标悬停在自动完成组件上且自动完成组件具有值时（桌面端），或当自动完成组件具有值时（移动端），它是可见的。

AutocompleteItem 在 base 元素上具有以下属性

• data-disabled: 当自动完成项目被禁用时。基于自动完成组件的 disabledKeys prop。
• data-selected: 当自动完成项目被选中时。基于自动完成组件的 selectedKey prop。
• data-hover: 当鼠标悬停在自动完成项目上时。基于 useHover
• data-pressed: 当自动完成项目被按下时。基于 usePress
• data-focus: 当自动完成项目被聚焦时。基于 useFocusRing。
• data-focus-visible: 当使用键盘聚焦自动完成项目时。基于 useFocusRing。

无障碍功能

• 支持通过输入文字过滤选项列表
• 支持选择单个选项
• 支持禁用选项
• 支持 sections 中的项目分组
• 支持自定义用户输入值
• 支持受控和非受控选项、选择、输入值和打开状态
• 支持自定义过滤函数
• 异步加载和无限滚动支持
• 支持虚拟化滚动，以提高长列表的性能
• 作为带有 ARIA 的组合框暴露给辅助技术
• 标签支持无障碍访问
• 必填和无效状态通过 ARIA 暴露给辅助技术
• 支持鼠标、触摸和键盘交互
• 键盘支持使用箭头键打开组合框列表，包括自动聚焦到第一个或最后一个项目
• 支持在输入时、聚焦时或手动打开列表框
• 处理来自触摸屏阅读器的输入虚拟点击，以切换列表框
• 组合框列表框选项导航的虚拟焦点管理
• 当列表框在 portal 中打开时，对辅助技术隐藏输入框和列表框之外的元素
• 自定义本地化公告，用于选项聚焦、过滤和选择，使用 ARIA live region 以解决 VoiceOver 错误
• 支持通过 ARIA 链接到输入框的描述和错误消息帮助文本

API

Autocomplete Props

Autocomplete Events

AutocompleteItem Props

查看 ListboxItem props。

AutocompleteItem Events

查看 ListboxItem events。

AutocompleteSection Props

查看 ListboxSection props。

类型

菜单触发操作