logoAnt Design

⌘ K
  • 设计
  • 研发
  • 组件
  • 博客
  • 资源
  • 国内镜像
5.25.2
  • 组件总览
  • 通用
    • Button按钮
    • FloatButton悬浮按钮
      5.0.0
    • Icon图标
    • Typography排版
  • 布局
    • Divider分割线
    • Flex弹性布局
      5.10.0
    • Grid栅格
    • Layout布局
    • Space间距
    • Splitter分隔面板
      5.21.0
  • 导航
    • Anchor锚点
    • Breadcrumb面包屑
    • Dropdown下拉菜单
    • Menu导航菜单
    • Pagination分页
    • Steps步骤条
    • Tabs标签页
  • 数据录入
    • AutoComplete自动完成
    • Cascader级联选择
    • Checkbox多选框
    • ColorPicker颜色选择器
      5.5.0
    • DatePicker日期选择框
    • Form表单
    • Input输入框
    • InputNumber数字输入框
    • Mentions提及
    • Radio单选框
    • Rate评分
    • Select选择器
    • Slider滑动输入条
    • Switch开关
    • TimePicker时间选择框
    • Transfer穿梭框
    • TreeSelect树选择
    • Upload上传
  • 数据展示
    • Avatar头像
    • Badge徽标数
    • Calendar日历
    • Card卡片
    • Carousel走马灯
    • Collapse折叠面板
    • Descriptions描述列表
    • Empty空状态
    • Image图片
    • List列表
    • Popover气泡卡片
    • QRCode二维码
      5.1.0
    • Segmented分段控制器
    • Statistic统计数值
    • Table表格
    • Tag标签
    • Timeline时间轴
    • Tooltip文字提示
    • Tour漫游式引导
      5.0.0
    • Tree树形控件
  • 反馈
    • Alert警告提示
    • Drawer抽屉
    • Message全局提示
    • Modal对话框
    • Notification通知提醒框
    • Popconfirm气泡确认框
    • Progress进度条
    • Result结果
    • Skeleton骨架屏
    • Spin加载中
    • Watermark水印
      5.1.0
  • 其他
    • Affix固钉
    • App包裹组件
      5.1.0
    • ConfigProvider全局化配置
    • Util工具类
      5.13.0

AutoComplete
自动完成

输入框自动完成功能。
使用import { AutoComplete } from "antd";
源码components/auto-complete
文档
编辑此页更新日志

相关资源

Ant Design X
Ant Design Charts
Ant Design Pro
Pro Components
Ant Design Mobile
Ant Design Mini
Ant Design Web3
Ant Design Landing-首页模板集
Scaffolds-脚手架市场
Umi-React 应用开发框架
dumi-组件/文档研发工具
qiankun-微前端框架
Ant Motion-设计动效
国内镜像站点 🇨🇳

社区

Awesome Ant Design
Medium
Twitter
yuque logoAnt Design 语雀专栏
Ant Design 知乎专栏
体验科技专栏
seeconf logoSEE Conf-蚂蚁体验科技大会
加入我们

帮助

GitHub
更新日志
常见问题
报告 Bug
议题
讨论区
StackOverflow
SegmentFault

Ant XTech logo更多产品

yuque logo语雀-构建你的数字花园
AntV logoAntV-数据可视化解决方案
Egg logoEgg-企业级 Node.js 框架
Kitchen logoKitchen-Sketch 工具集
Galacean logoGalacean-互动图形解决方案
xtech logo蚂蚁体验科技
主题编辑器
Made with ❤ by
蚂蚁集团和 Ant Design 开源社区

何时使用

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

和 Select 的区别是:

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

代码演示

input here


control mode
基本使用

基本使用,通过 options 设置自动完成的数据源。

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
自定义输入组件

自定义输入组件。

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
查询模式 - 确定类目

查询模式: 确定类目 示例。

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
自定义状态

使用 status 为 AutoComplete 添加状态,可选 error 或者 warning。

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
UnClearable


Customized clear icon
自定义清除按钮

自定义清除按钮

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
input here
自定义选项

可以返回自定义的 Option label

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
try to type `b`
不区分大小写

不区分大小写的 AutoComplete

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
查询模式 - 不确定类目

查询模式: 不确定类目 示例。

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
Outlined
Filled
Borderless
多种形态

可选 outlined filled borderless 三种形态。

CodeSandbox Icon
codepen icon
External Link Icon
expand codeexpand code
5.13.0

API

通用属性参考:通用属性

参数说明类型默认值版本
allowClear支持清除boolean | { clearIcon?: ReactNode }false5.8.0: 支持对象形式
autoFocus自动获取焦点booleanfalse
backfill使用键盘选择选项的时候把选中项回填到输入框中booleanfalse
children (自动完成的数据源)自动完成的数据源,不能和自定义输入框同时配置React.ReactElement<OptionProps> | Array<React.ReactElement<OptionProps>>-
children (自定义输入框)自定义输入框,不能和自动完成的数据源同时配置HTMLInputElement | HTMLTextAreaElement | React.ReactElement<InputProps><Input />
classNames语义化结构 classRecord<SemanticDOM, string>-5.25.0
defaultActiveFirstOption是否默认高亮第一个选项booleantrue
defaultOpen是否默认展开下拉菜单boolean-
defaultValue指定默认选中的条目string-
disabled是否禁用booleanfalse
dropdownRender自定义下拉框内容,使用 popupRender 替换(originNode: ReactNode) => ReactNode-4.24.0
popupRender自定义下拉框内容(originNode: ReactNode) => ReactNode-
popupClassName下拉菜单的 className 属性,使用 classNames.popup.root 替换string-4.23.0
dropdownStyle下拉菜单的 style 属性,使用 styles.popup.root 替换CSSProperties-
popupMatchSelectWidth下拉菜单和选择器同宽。默认将设置 min-width,当值小于选择框宽度时会被忽略。false 时会关闭虚拟滚动boolean | numbertrue
filterOption是否根据输入项进行筛选。当其为一个函数时,会接收 inputValue option 两个参数,当 option 符合筛选条件时,应返回 true,反之则返回 falseboolean | 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-
styles语义化结构 styleRecord<SemanticDOM, CSSProperties>-5.25.0
value指定当前选中的条目string-
variant形态变体outlined | borderless | filledoutlined5.13.0
virtual设置 false 时关闭虚拟滚动booleantrue4.1.0
onBlur失去焦点时的回调function()-
onChange选中 option,或 input 的 value 变化时,调用此函数function(value)-
onDropdownVisibleChange展开下拉菜单的回调,使用 onOpenChange 替换(open: boolean) => void-
onOpenChange展开下拉菜单的回调(open: boolean) => void-
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()获取焦点

Semantic DOM

input here
  • root
    5.25.0
    根元素
  • popup.root
    5.25.0
    弹出菜单元素

主题变量(Design Token)

组件 Token如何定制?
Token 名称描述类型默认值
activeBorderColor激活态边框色string#1677ff
activeOutlineColor激活态 outline 颜色stringrgba(5,145,255,0.1)
clearBg清空按钮背景色string#ffffff
hoverBorderColor悬浮态边框色string#4096ff
multipleItemBg多选标签背景色stringrgba(0,0,0,0.06)
multipleItemBorderColor多选标签边框色stringtransparent
multipleItemBorderColorDisabled多选标签禁用边框色stringtransparent
multipleItemColorDisabled多选标签禁用文本颜色stringrgba(0,0,0,0.25)
multipleItemHeight多选标签高度number24
multipleItemHeightLG大号多选标签高度number32
multipleItemHeightSM小号多选标签高度number16
multipleSelectorBgDisabled多选框禁用背景stringrgba(0,0,0,0.04)
optionActiveBg选项激活态时背景色stringrgba(0,0,0,0.04)
optionFontSize选项字体大小number14
optionHeight选项高度number32
optionLineHeight选项行高undefined | LineHeight<string | number>1.5714285714285714
optionPadding选项内间距undefined | Padding<string | number>5px 12px
optionSelectedBg选项选中时背景色string#e6f4ff
optionSelectedColor选项选中时文本颜色stringrgba(0,0,0,0.88)
optionSelectedFontWeight选项选中时文本字重undefined | FontWeight600
selectorBg选框背景色string#ffffff
showArrowPaddingInlineEnd箭头的行末内边距number18
singleItemHeightLG单选大号回填项高度number40
zIndexPopup下拉菜单 z-indexnumber1050
全局 Token如何定制?

FAQ

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

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

相关 issue:#18230 #17916

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

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