自动补全

自动补全将文本输入与列表框结合起来，允许用户将选项列表筛选为与查询匹配的项目。

安装

npx nextui-cli@latest add autocomplete

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

导入

NextUI 导出了 3 个与自动补全相关的组件

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

用法

动态项

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

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

禁用

已禁用项

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

必需

如果你将 isRequired 属性传递给自动完成，它将在标签的末尾有一个 danger 星号，并且自动完成将是必需的。

只读

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

大小

颜色

变体

标签位置

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

注意：如果没有传递 label，则 labelPlacement 属性将默认设置为 outside。

开始内容

你可以使用 startContent 和 endContent 属性在自动完成的开始和结束添加内容。

项目开始和结束内容

由于 Autocomplete 组件在底层使用了 Listbox 组件，因此您可以使用 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 钩子来管理项目的筛选。

npm install @react-aria/i18n

import {useFilter} from "@react-aria/i18n";

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

自定义项目

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

自定义空内容消息

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

自定义筛选

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

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

异步过滤

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

npm install @react-stately/data

import {useAsyncList} from "@react-stately/data";

异步加载

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

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

npm install @nextui-org/use-infinite-scroll

import {useInfiniteScroll} from "@nextui-org/use-infinite-scroll";

带分区的

你可以使用 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 属性。

AutocompleteItem 事件

查看ListboxItem 事件。

AutocompleteSection 属性

查看ListboxSection 属性。

类型

菜单触发器操作

type MenuTriggerAction = "focus" | "input" | "manual";