自动补全 AutoComplete

输入框或自定义输入控件的自动补全功能。

安装

npm install @arco-design/web-react@2.66.18

在入口引入 @arco-design/web-react/dist/css/arco.css，用 ConfigProvider 设置语言。React 19 项目还需在入口最先引入 @arco-design/web-react/es/_util/react-19-adapter，否则 Message、Modal 等命令式 API 无法渲染。

示例

基础用法：根据当前输入展示输入建议（下拉选择）。
自定义选项：可以传入 AutoComplete.Option 作为组件的 children，而非使用 data。
自定义输入组件：支持自定义输入组件。
区分大小写：使用 strict=true 来指明在匹配时严格区分大小写。
复杂用法：这个示例展示了：1. 添加Tooltip, 2. 自定义显示, 3. 对值进行操控。
查询模式确定类目：根据查询结果补全输入内容（确定类目）。
查询模式不确定类目：根据查询结果补全输入内容（不确定类目）。
自定义过滤规则：如果你依赖用户输入来动态更新选项，请通过 filterOption 属性来覆盖默认的选项过滤规则，或者将其设为 false 来关闭默认过滤规则。

示例来自 Arco Design 官方仓库（MIT），固定在 npm 2.66.18 对应的提交；部分示例使用在线图片或上传地址，预览中网络请求被禁用。

API

AutoComplete

参数名	描述	类型	默认值	版本
allowClear	是否允许一键清除	boolean	`-`	-
defaultActiveFirstOption	是否默认高亮第一个选项	boolean	`true`	-
disabled	是否禁用	boolean	`-`	-
error	是否是错误状态。(废弃，下个大版本移除，使用 status='error' 替代)	boolean	`-`	-
loading	是否处于加载状态。	boolean	`-`	2.10.0
strict	`strict: true` 的时候大小写敏感	boolean	`-`	-
defaultValue	自动补全组件的默认值	string	`-`	-
placeholder	输入框提示	string	`-`	-
value	自动补全组件的值（受控模式）	string	`-`	-
status	状态	'error' \| 'warning'	`-`	2.45.0
children	自定义输入框/数据源	ReactNode	`-`	-
className	节点类名	string \| string[]	`-`	-
data	自动完成的数据源	(string \| { value: string; name: string; [key: string]: any } \| ReactNode)[]	`-`	-
inputProps	传递 Input 组件的属性。	Partial<InputProps>	`-`	2.10.0
style	节点样式	CSSProperties	`-`	-
triggerProps	可以接受所有 `Trigger` 的 `Props`	Partial<TriggerProps>	`-`	-
virtualListProps	传递虚拟滚动属性。	AvailableVirtualListProps	`-`	2.2.0
dropdownRender	自定义弹出内容。	(menu: ReactNode) => ReactNode	`-`	-
filterOption	是否根据输入的值筛选数据。如果传入函数的话，接收 `inputValue` 和 `option` 两个参数，当option符合筛选条件时，返回 `true`，反之返回 `false`。	boolean \| ((inputValue: string, option: ReactElement) => boolean)	`true`	-
getPopupContainer	弹出框挂载的父节点。	(node: HTMLElement) => Element	`-`	-
onBlur	失去焦点的回调	(event) => void	`-`	-
onChange	输入或者点击补全项，value 改变时的回调（仅在点击补全项时存在第二个参数）	(value: string, option?: OptionInfo) => void	`-`	-
onFocus	聚焦时的回调	(event) => void	`-`	-
onPressEnter	按下回车键的回调	(event, activeOption?: OptionInfo) => void	`-`	`activeOption` in 2.25.1
onSearch	搜索补全时的回调	(value: string) => void	`-`	-
onSelect	点击补全项时的回调	(value: string, option: OptionInfo) => void	`-`	-
triggerElement	自定义触发元素	ReactElement \| (({ value }) => ReactElement)	`<Input />`	`() => ReactElement` in 2.31.0

OptionInfo

export interface OptionInfo extends PropsWithChildren<OptionProps> {
  child?: ReactElement;
  _valid: boolean;
  _index: number;
  _origin: "children" | "options" | "userCreatedOptions" | "userCreatingOption";
}

AvailableVirtualListProps

export type AvailableVirtualListProps = Pick<
  VirtualListProps<any>,
  | "height"
  | "itemHeight"
  | "threshold"
  | "isStaticItemHeight"
  | "scrollOptions"
  | "onScroll"
  | "wrapperChild"
>;

AutoComplete.Option

同 Select.Option, 参考 Select 文档。

AutoComplete.OptGroup

同 Select.OptGroup, 参考 Select 文档。