ant-design/components/auto-complete/index.zh-CN.md

category	subtitle	cols	title	cover	group
Components	自动完成	2	AutoComplete	https://gw.alipayobjects.com/zos/alicdn/qtJm4yt45/AutoComplete.svg	title order 数据录入 4

输入框自动完成功能。

何时使用

• 需要一个输入框而不是选择器。
• 需要输入建议/辅助提示。

和 Select 的区别是：

• AutoComplete 是一个带提示的文本输入框，用户可以自由输入，关键词是辅助输入。
• Select 是在限定的可选项中进行选择，关键词是选择。

代码演示

基本使用 自定义选项 自定义输入组件 不区分大小写 查询模式 - 确定类目 查询模式 - 不确定类目 自定义状态 在 Form 中 Debug _InternalPanelDoNotUseOrYouWillBeFired

API

参数	说明	类型	默认值	版本
allowClear	支持清除	boolean	false
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
popupClassName	下拉菜单的 className 属性	string	-	4.23.0
dropdownMatchSelectWidth	下拉菜单和选择器同宽。默认将设置 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
value	指定当前选中的条目	string	-
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

方法

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

FAQ

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

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

相关 issue：#18230 #17916

v3 的部分属性为何在 v4 中没有了？

AutoComplete 组件是一个支持自动提示的 Input 组件，因而其不具有 labelInValue 等影响 value 展示的属性。在 v3 版本，AutoComplete 实现存在输入值如果遇到 value 与 label 相同时无法映射的问题。 v4 中不再支持 label 为值的输入形态。

此外为了统一 API，dataSource 改为 options 你可以如下转换：

v3

dataSource = ['light', 'bamboo'];
// or
dataSource = [
  { value: 'light', text: 'Light' },
  { value: 'bamboo', text: 'Bamboo' },
];

v4

options = [
  { value: 'light', label: 'Light' },
  { value: 'bamboo', label: 'Bamboo' },
];