自动完成

自动完成组件结合了文本输入框和列表框，允许用户根据查询条件筛选选项列表。

安装

The above command is for individual installation only. You may skip this step if @heroui/react is already installed globally.

导入

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

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

用法

动态项

自动完成遵循 集合组件 API，接受静态和动态集合。

• 静态：上面的用法示例展示了静态实现，适用于提前知道完整选项列表的情况。
• 动态：下面的示例适用于选项来自外部数据源（如 API 调用）或随时间更新的情况。

禁用

禁用项

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

必填

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

只读

如果将 isReadOnly 属性传递给自动完成组件，列表框将打开以显示所有可用选项，但用户无法选择列出的任何选项。

尺寸

颜色

变体

标签位置

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

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

起始内容

您可以使用 startContent 和 endContent 属性在自动完成的起始和末尾添加内容。

项起始和结束内容

由于 Autocomplete 组件底层使用 列表框 组件，您可以使用 AutocompleteItem 组件的 startContent 和 endContent 属性在自动完成项的起始和末尾添加内容。

自定义值

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

自定义选择器图标

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

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

无滚动阴影

自动完成组件底层使用 滚动阴影 在自动完成内容可滚动时显示阴影。您可以通过使用 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 钩子来管理项的筛选。

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

自定义项

您可以通过修改 AutocompleteItem 子项来自定义自动完成项。

自定义空内容消息

默认情况下，如果筛选器查询没有匹配结果，将显示消息 未找到结果。。您可以通过修改 listboxProps 中的 emptyContent 来自定义空内容消息。

自定义筛选

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

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

异步筛选

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

异步加载

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

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

虚拟化

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

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

一万个项

包含 10,000 个项的虚拟化。

最大列表框高度

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

自定义项高度

itemHeight 属性用于设置列表框中每个项的高度。使用虚拟化时需要此属性。默认情况下，它设置为 32。

注意：如果由于 startContent 或其他自定义内容导致列表项的高度与默认值不同，请确保将正确的值传递给 itemHeight 以防止布局问题。

带分组

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

自定义分组样式

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

自定义自动完成

您可以使用 classNames 属性来自定义自动完成的任何插槽。自动完成组件还提供 popoverProps、listboxProps、inputProps 属性来自定义弹出框、列表框和输入组件。

插槽

• base：自动完成的主包装器。包装输入和弹出框组件。
• listboxWrapper：列表框的包装器。包装列表框组件，此插槽位于滚动阴影组件之上。
• popoverContent：弹出框内容插槽。用于修改弹出框内容样式。
• endContentWrapper：结束内容的包装器。包装清除按钮和选择器按钮。
• clearButton：清除按钮插槽。
• selectorButton：选择器按钮插槽。

数据属性

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

• data-invalid： 当自动完成无效时。基于 isInvalid 属性。
• data-open： 指示自动完成的弹出框是否打开。

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

• data-open： 指示自动完成的弹出框是否打开。

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

• data-visible： 指示自动完成的清除按钮是否可见。默认情况下，当悬停在自动完成上且自动完成有值时（桌面）或自动完成有值时（移动设备）可见。

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

• data-disabled： 当自动完成项被禁用时。基于自动完成 disabledKeys 属性。
• data-selected： 当自动完成项被选中时。基于自动完成 selectedKey 属性。
• data-hover： 当自动完成项被悬停时。基于 useHover
• data-pressed： 当自动完成项被按下时。基于 usePress
• data-focus： 当自动完成项获得焦点时。基于 useFocusRing。
• data-focus-visible： 当自动完成项通过键盘获得焦点时。基于 useFocusRing。

无障碍性

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

API

Autocomplete 属性

Autocomplete 事件

AutocompleteItem 属性

查看 ListboxItem 属性。

AutocompleteItem 事件

查看 ListboxItem 事件。

AutocompleteSection 属性

查看 ListboxSection 属性。

类型

菜单触发操作