Autocomplete 自动完成

用法

import { Autocomplete, useFilter } from "@heroui/react";

组件结构

import {Autocomplete, Label, Description, SearchField, ListBox} from "@heroui/react";

export default () => (
  <Autocomplete>
    <Label />
    <Autocomplete.Trigger>
      <Autocomplete.Value />
      <Autocomplete.ClearButton />
      <Autocomplete.Indicator />
    </Autocomplete.Trigger>
    <Description />
    <Autocomplete.Popover>
      <Autocomplete.Filter>
        <SearchField>
          <SearchField.Group>
            <SearchField.SearchIcon />
            <SearchField.Input />
          </SearchField.Group>
        </SearchField>
        <ListBox>
          <ListBox.Item>
            <Label />
            <ListBox.ItemIndicator />
          </ListBox.Item>
        </ListBox>
      </Autocomplete.Filter>
    </Autocomplete.Popover>
  </Autocomplete>
);

示例

变体

Autocomplete 组件支持两种视觉变体：

• primary（默认）- 标准样式带阴影，适用于大多数场景
• secondary - 低强调变体无阴影，适用于 Surface 组件内

宽度充满

带描述

必填

禁用

含禁用选项

允许空选项

allowsEmptyCollection 属性允许集合为空时仍可使用自动完成，适用于列表初始为空或全部被过滤掉的场景。

分组选项

多选

受控组件

受控多选

受控展开状态

异步搜索

自定义指示器

自定义展示值

可使用 render props 自定义显示值：

表面样式

在 Surface 组件内使用时，请使用 variant="secondary" 以应用适合 Surface 背景的低强调变体。

虚拟滚动

Autocomplete 通过 Virtualizer 支持虚拟化，仅渲染视口内可见行以高效处理大数据集。

高级示例

用户选择

用户多选

地点搜索

标签组选择

邮件收件人

自定义样式

Tailwind CSS

全局 CSS

可使用 @layer components 指令自定义 Autocomplete 组件类。

了解更多。

@layer components {
  .autocomplete {
    @apply flex flex-col gap-1;
  }

  .autocomplete__trigger {
    @apply rounded-lg border border-border bg-surface p-2;
  }

  .autocomplete__value {
    @apply text-current;
  }

  .autocomplete__clear-button {
    @apply text-muted hover:text-foreground;
  }

  .autocomplete__indicator {
    @apply text-muted;
  }

  .autocomplete__popover {
    @apply rounded-lg border border-border bg-surface p-2;
  }
}

样式参考

HeroUI 遵循 BEM 方法论，确保组件变体与状态可复用且易于自定义。

CSS 类

Autocomplete 组件使用以下 CSS 类（查看源码样式）：

基础类

• .autocomplete - 自动完成根容器
• .autocomplete__trigger - 触发自动完成的按钮
• .autocomplete__value - 显示的值或占位符
• .autocomplete__clear-button - 清除已选值的按钮
• .autocomplete__indicator - 下拉指示图标
• .autocomplete__popover - 弹出层容器
• .autocomplete__filter - 过滤包装器

变体类

• .autocomplete--primary - 带阴影的主变体（默认）
• .autocomplete--secondary - 无阴影的次变体，适用于 Surface 内

状态类

• .autocomplete[data-invalid="true"] - 无效状态
• .autocomplete__trigger[data-focus-visible="true"] - 触发器聚焦状态
• .autocomplete__trigger[data-disabled="true"] - 触发器禁用状态
• .autocomplete__value[data-placeholder="true"] - 占位符状态
• .autocomplete__clear-button[data-empty="true"] - 无选择时隐藏清除按钮
• .autocomplete__indicator[data-open="true"] - 打开时的指示器状态

交互状态

组件同时支持 CSS 伪类与 data 属性：

• Hover：触发器上的 :hover 或 [data-hovered="true"]
• Focus：触发器上的 :focus-visible 或 [data-focus-visible="true"]
• Disabled：Autocomplete 上的 :disabled 或 [data-disabled="true"]
• Open：指示器上的 [data-open="true"]

API 参考

Autocomplete

Autocomplete.Trigger

Autocomplete.Value

Autocomplete.Indicator

Autocomplete.ClearButton

Autocomplete.Popover

Autocomplete.Filter

useFilter Hook

React Aria 的 useFilter hook 提供自动完成过滤函数。

import {useFilter} from "@heroui/react";

const {contains} = useFilter({sensitivity: "base"});

<Autocomplete.Filter filter={contains}>
  <SearchField>...</SearchField>
  <ListBox>...</ListBox>
</Autocomplete.Filter>

Options:

Returns:

Render Props

使用 Autocomplete.Value 的 render 函数时，提供以下值：

无障碍

Autocomplete 组件实现带过滤的 ARIA select 模式，提供：

• 完整键盘导航支持
• 选择变化的屏幕阅读器播报
• 正确的焦点管理
• 禁用状态支持
• 带过滤的搜索功能
• HTML 表单集成

更多信息请参阅 React Aria Select 文档。

相关组件