输入类 · AutoComplete
自动完成
输入框自动填充。

使用场景

用于对输入框提供输入建议,进行自动补全的操作
与可搜索的 Select 组件的区别:
  • AutoComplete 本质上是一个增强型的提供了输入建议的 Input 组件,而 Select 是一个选择器
  • 点击展开时,Select 会将输入框的值全部清空,而 AutoComplete 会保留上次选中的值
  • Select 的已选项渲染(renderSelectedItem)可定制化程度更高,可以为任意类型的 ReactNode,而 AutoComplete 只允许为字符串

代码演示

如何引入

基本用法

通过 onSearch 监听用户输入,将输入建议通过 data 传入,通过 onChange 保持受控,当输入框变化/选中输入项时会触发 onChange

自定义候选项渲染

需要自定义候选项渲染时,data 可以传入一个对象数组(每个 Object 必须含有 label、value 两个 key,value 为候选项选中的值,label 为候选项展示的内容)
通过 renderItem 可以自定义候选项的渲染

远程搜索

从 onSearch 中获取用户输入值,动态更新 data 值,更新 loading

尺寸

通过设置 size 可设置输入框尺寸,可选smalldefault(默认),large

下拉菜单的位置

通过设置 position 可设置下拉菜单位置,可选值参考 Tooltip position

禁用

校验状态

可设置不同校验状态,展示不同样式

自定义空内容

可设置自定义展示空内容

API 参考

属性说明类型默认值版本
autoFocus是否自动聚焦boolfalse1.16.0
autoAdjustOverflow浮层被遮挡时是否自动调整方向booltrue0.27.0
className样式类名string
clearIcon可用于自定义清除按钮, showClear为true时有效ReactNode2.25.0
data候选项的数据源,可以为字符串数组或对象数组array[]
defaultActiveFirstOption是否默认高亮第一个选项(按回车可直接选中)boolfalse
defaultOpen是否默认展开下拉菜单booleanfalse
defaultValue默认值string
disabled是否禁用booleanfalse
dropdownClassName下拉列表的 CSS 类名string
dropdownStyle下拉列表的内联样式object
emptyContentdata 为空时自定义下拉内容ReactNodenull1.16.0
getPopupContainer指定父级 DOM,下拉列表浮层将会渲染至该 DOM 中,自定义需要设置 position: relative 这会改变浮层 DOM 树位置,但不会改变视图渲染位置。() => HTMLElement() => document.body
loading下拉列表是否展示加载动画booleanfalse
maxHeight下拉列表的最大高度number|string300
motion下拉列表出现/隐藏时,是否有动画booleantrue
onSelectWithObject点击候选项时,是否将选中项 option 的其他属性也作为回调入参。设为 true 时,onSelect 的入参类型会从 string 变为 object: { value, label, ...rest }booleanfalse1.23.0
placeholder输入框提示string
position下拉菜单的显示位置,可选值同 tooltip 组件string'bottomLeft'
prefix选择框的前缀标签ReactNode0.23.0
renderItem控制下拉列表候选项的渲染(option: string|Item)=> React.Node
renderSelectedItem通过 renderSelectedItem 自定义下拉列表候选项被点击选中后,在选择框中的渲染内容
仅支持 String 类型的返回值
(option: string|Item) => string0.23.0
showClear是否展示清除按钮booleanfalse
size尺寸,可选small, default, largestringdefault
style样式object
suffix选择框的前缀标签ReactNode0.23.0
validateStatus校验状态,可选值defaulterrorwarning,默认 default。仅影响展示样式string'default'1.14.0
value当前值string|number
zIndex下拉菜单的 zIndexnumber
onBlur失去焦点时的回调Function(event)
onChange输入框变化/候选项选中时变化Function(value:string|number)1.23.0
onFocus获得焦点时的回调Function(event)
onKeyDownkeydown 回调(e: React.KeyboardEvent) => void2.21.0
onSearch输入变化时的回调Function(value: string)
onSelect下拉菜单候选项被选中时的回调Function(item: string|number|Item)

Accessibility

键盘和焦点

  • AutoComplete 的 input 框可被聚焦,聚焦后,键盘用户可以通过 上箭头下箭头 打开选项面板(如有)
  • AutoComplete 也支持通过 Enter 键打开和收起面板
  • 若用户将 defaultActiveFirstOption 属性设置为 true 时,选项面板打开后默认高亮第一个选项
  • 若下拉菜单打开时:
    • 使用 Esc 可以关闭菜单
    • 使用 上箭头下箭头 可以切换选项
    • 被聚焦的选项可以通过 Enter 键选中,并收起面板

文案规范

  • 需要清晰地展示内容,让用户显而易见地感知到可用的各个选项
  • 限制一次性展示的选项数量

设计变量