自动补全

自动补全将文本输入框与列表框结合在一起，允许用户过滤选项列表，查找与查询匹配的项目。

安装

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

导入

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

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

用法

动态项目

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

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

已禁用

已禁用项目

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

必填

如果您将 isRequired 属性传递给自动完成组件，标签末尾将出现一个 danger 星号，并且该自动完成组件将变为必填项。

只读

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

尺寸

颜色

变体

标签位置

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

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

起始内容

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

项目起始和结束内容

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

自定义值

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

自定义选择器图标

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

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

无滚动阴影

自动完成组件在底层使用 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 的子元素来自定义自动完成项目。

自定义空内容消息

默认情况下，如果没有与您的过滤器匹配的查询结果，将显示消息 未找到结果。。您可以通过修改 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 个条目的虚拟化。

最大列表框高度

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

自定义项目高度

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

带有节

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

自定义节样式

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

自定义自动完成

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

插槽

• base：自动完成的主要包装器。它包裹了输入框和弹出框组件。
• listboxWrapper：列表框的包装器。它包裹了列表框组件，此插槽用于滚动阴影组件之上。
• listbox：列表框组件。这是包裹自动完成项目的组件。
• 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

自动完成属性

自动完成事件

自动完成项属性

请查看 ListboxItem 的属性。

自动完成项事件

请查看 ListboxItem 的事件。

自动完成节属性

请查看 ListboxSection 的属性。

类型

菜单触发操作