AutoComplete
自动完成

参数	说明	类型	默认值	版本
allowClear	支持清除	boolean \| { clearIcon?: ReactNode }	false	5.8.0: 支持对象形式
autoFocus	自动获取焦点	boolean	false
backfill	使用键盘选择选项的时候把选中项回填到输入框中	boolean	false
children (自动完成的数据源)	自动完成的数据源，不能和自定义输入框同时配置	React.ReactElement<OptionProps> \| Array<React.ReactElement<OptionProps>>	-
children (自定义输入框)	自定义输入框，不能和自动完成的数据源同时配置	HTMLInputElement \| HTMLTextAreaElement \| React.ReactElement<InputProps>	<Input />
defaultActiveFirstOption	是否默认高亮第一个选项	boolean	true
defaultOpen	是否默认展开下拉菜单	boolean	-
defaultValue	指定默认选中的条目	string	-
disabled	是否禁用	boolean	false
dropdownRender	自定义下拉框内容	(menus: ReactNode) => ReactNode	-	4.24.0
popupClassName	下拉菜单的 className 属性	string	-	4.23.0
popupMatchSelectWidth	下拉菜单和选择器同宽。默认将设置 `min-width`，当值小于选择框宽度时会被忽略。false 时会关闭虚拟滚动	boolean \| number	true
filterOption	是否根据输入项进行筛选。当其为一个函数时，会接收 `inputValue` `option` 两个参数，当 `option` 符合筛选条件时，应返回 true，反之则返回 false	boolean \| function(inputValue, option)	true
getPopupContainer	菜单渲染父节点。默认渲染到 body 上，如果你遇到菜单滚动定位问题，试试修改为滚动的区域，并相对其定位。示例	function(triggerNode)	() => document.body
notFoundContent	当下拉列表为空时显示的内容	ReactNode	-
open	是否展开下拉菜单	boolean	-
options	数据化配置选项内容，相比 jsx 定义会获得更好的渲染性能	{ label, value }[]	-
placeholder	输入框提示	string	-
status	设置校验状态	'error' \| 'warning'	-	4.19.0
size	控件大小	`large` \| `middle` \| `small`	-
value	指定当前选中的条目	string	-
variant	形态变体	`outlined` \| `borderless` \| `filled`	`outlined`	5.13.0
virtual	设置 false 时关闭虚拟滚动	boolean	true	4.1.0
onBlur	失去焦点时的回调	function()	-
onChange	选中 option，或 input 的 value 变化时，调用此函数	function(value)	-
onDropdownVisibleChange	展开下拉菜单的回调	function(open)	-
onFocus	获得焦点时的回调	function()	-
onSearch	搜索补全项的时候调用	function(value)	-
onSelect	被选中时调用，参数为选中项的 value 值	function(value, option)	-
onClear	清除内容时的回调	function	-	4.6.0
onInputKeyDown	按键按下时回调	(event: KeyboardEvent) => void	-
onPopupScroll	下拉列表滚动时的回调	(event: UIEvent) => void	-

方法

名称	描述	版本
blur()	移除焦点
focus()	获取焦点

主题变量（Design Token）

组件 Token如何定制？

Token 名称	描述	类型	默认值
activeBorderColor	激活态边框色	string	#1677ff
activeOutlineColor	激活态 outline 颜色	string	rgba(5,145,255,0.1)
clearBg	清空按钮背景色	string	#ffffff
hoverBorderColor	悬浮态边框色	string	#4096ff
multipleItemBg	多选标签背景色	string	rgba(0,0,0,0.06)
multipleItemBorderColor	多选标签边框色	string	transparent
multipleItemBorderColorDisabled	多选标签禁用边框色	string	transparent
multipleItemColorDisabled	多选标签禁用文本颜色	string	rgba(0,0,0,0.25)
multipleItemHeight	多选标签高度	number	24
multipleItemHeightLG	大号多选标签高度	number	32
multipleItemHeightSM	小号多选标签高度	number	16
multipleSelectorBgDisabled	多选框禁用背景	string	rgba(0,0,0,0.04)
optionActiveBg	选项激活态时背景色	string	rgba(0,0,0,0.04)
optionFontSize	选项字体大小	number	14
optionHeight	选项高度	number	32
optionLineHeight	选项行高	undefined \| LineHeight<string \| number>	1.5714285714285714
optionPadding	选项内间距	undefined \| Padding<string \| number>	5px 12px
optionSelectedBg	选项选中时背景色	string	#e6f4ff
optionSelectedColor	选项选中时文本颜色	string	rgba(0,0,0,0.88)
optionSelectedFontWeight	选项选中时文本字重	undefined \| FontWeight	600
selectorBg	选框背景色	string	#ffffff
showArrowPaddingInlineEnd	箭头的行末内边距	number	18
singleItemHeightLG	单选大号回填项高度	number	40
zIndexPopup	下拉菜单 z-index	number	1050

全局 Token如何定制？

FAQ

为何受控状态下使用 onSearch 无法输入中文？

请使用 onChange 进行受控管理。onSearch 触发于搜索输入，与 onChange 时机不同。此外，点击选项时也不会触发 onSearch 事件。

为何 options 为空时，受控 open 展开不会显示下拉菜单？

AutoComplete 组件本质上是 Input 输入框的一种扩展，当 options 为空时，显示空文本会让用户误以为该组件不可操作，实际上它仍然可以进行文本输入操作。因此，为了避免给用户带来困惑，当 options 为空时，open 属性为 true 也不会展示下拉菜单，需要与 options 属性配合使用。

AutoComplete自动完成

何时使用

代码演示

API