AutoComplete自动完成

输入框自动完成功能。

何时使用

  • 需要一个输入框而不是选择器。

  • 需要输入建议/辅助提示。

和 Select 的区别是:

  • AutoComplete 是一个带提示的文本输入框,用户可以自由输入,关键词是辅助输入

  • Select 是在限定的可选项中进行选择,关键词是选择

代码演示

AutoComplete自动完成 - 图1

基本使用

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

TypeScript

JavaScript

AutoComplete自动完成 - 图2

  1. import React, { useState } from 'react';
  2. import { AutoComplete } from 'antd';
  3. const mockVal = (str: string, repeat: number = 1) => ({
  4. value: str.repeat(repeat),
  5. });
  6. const Complete: React.FC = () => {
  7. const [value, setValue] = useState('');
  8. const [options, setOptions] = useState<{ value: string }[]>([]);
  9. const onSearch = (searchText: string) => {
  10. setOptions(
  11. !searchText ? [] : [mockVal(searchText), mockVal(searchText, 2), mockVal(searchText, 3)],
  12. );
  13. };
  14. const onSelect = (data: string) => {
  15. console.log('onSelect', data);
  16. };
  17. const onChange = (data: string) => {
  18. setValue(data);
  19. };
  20. return (
  21. <>
  22. <AutoComplete
  23. options={options}
  24. style={{ width: 200 }}
  25. onSelect={onSelect}
  26. onSearch={onSearch}
  27. placeholder="input here"
  28. />
  29. <br />
  30. <br />
  31. <AutoComplete
  32. value={value}
  33. options={options}
  34. style={{ width: 200 }}
  35. onSelect={onSelect}
  36. onSearch={onSearch}
  37. onChange={onChange}
  38. placeholder="control mode"
  39. />
  40. </>
  41. );
  42. };
  43. ReactDOM.render(<Complete />, mountNode);

AutoComplete自动完成 - 图3

自定义输入组件

自定义输入组件。

TypeScript

JavaScript

AutoComplete自动完成 - 图4

  1. import React, { useState } from 'react';
  2. import { AutoComplete, Input } from 'antd';
  3. const { TextArea } = Input;
  4. const Complete: React.FC = () => {
  5. const [options, setOptions] = useState<{ value: string }[]>([]);
  6. const handleSearch = (value: string) => {
  7. setOptions(
  8. !value ? [] : [{ value }, { value: value + value }, { value: value + value + value }],
  9. );
  10. };
  11. const handleKeyPress = (ev: React.KeyboardEvent<HTMLTextAreaElement>) => {
  12. console.log('handleKeyPress', ev);
  13. };
  14. const onSelect = (value: string) => {
  15. console.log('onSelect', value);
  16. };
  17. return (
  18. <AutoComplete
  19. options={options}
  20. style={{ width: 200 }}
  21. onSelect={onSelect}
  22. onSearch={handleSearch}
  23. >
  24. <TextArea
  25. placeholder="input here"
  26. className="custom"
  27. style={{ height: 50 }}
  28. onKeyPress={handleKeyPress}
  29. />
  30. </AutoComplete>
  31. );
  32. };
  33. ReactDOM.render(<Complete />, mountNode);

AutoComplete自动完成 - 图5

查询模式 - 确定类目

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

TypeScript

JavaScript

AutoComplete自动完成 - 图6

  1. import { Input, AutoComplete } from 'antd';
  2. import { UserOutlined } from '@ant-design/icons';
  3. const renderTitle = (title: string) => (
  4. <span>
  5. {title}
  6. <a
  7. style={{ float: 'right' }}
  8. href="https://www.google.com/search?q=antd"
  9. target="_blank"
  10. rel="noopener noreferrer"
  11. >
  12. more
  13. </a>
  14. </span>
  15. );
  16. const renderItem = (title: string, count: number) => ({
  17. value: title,
  18. label: (
  19. <div
  20. style={{
  21. display: 'flex',
  22. justifyContent: 'space-between',
  23. }}
  24. >
  25. {title}
  26. <span>
  27. <UserOutlined /> {count}
  28. </span>
  29. </div>
  30. ),
  31. });
  32. const options = [
  33. {
  34. label: renderTitle('Libraries'),
  35. options: [renderItem('AntDesign', 10000), renderItem('AntDesign UI', 10600)],
  36. },
  37. {
  38. label: renderTitle('Solutions'),
  39. options: [renderItem('AntDesign UI FAQ', 60100), renderItem('AntDesign FAQ', 30010)],
  40. },
  41. {
  42. label: renderTitle('Articles'),
  43. options: [renderItem('AntDesign design language', 100000)],
  44. },
  45. ];
  46. const Complete: React.FC = () => (
  47. <AutoComplete
  48. dropdownClassName="certain-category-search-dropdown"
  49. dropdownMatchSelectWidth={500}
  50. style={{ width: 250 }}
  51. options={options}
  52. >
  53. <Input.Search size="large" placeholder="input here" />
  54. </AutoComplete>
  55. );
  56. ReactDOM.render(<Complete />, mountNode);
  1. .certain-category-search-dropdown .ant-select-dropdown-menu-item-group-title {
  2. color: #666;
  3. font-weight: bold;
  4. }
  5. .certain-category-search-dropdown .ant-select-dropdown-menu-item-group {
  6. border-bottom: 1px solid #f6f6f6;
  7. }
  8. .certain-category-search-dropdown .ant-select-dropdown-menu-item {
  9. padding-left: 16px;
  10. }
  11. .certain-category-search-dropdown .ant-select-dropdown-menu-item.show-all {
  12. text-align: center;
  13. cursor: default;
  14. }
  15. .certain-category-search-dropdown .ant-select-dropdown-menu {
  16. max-height: 300px;
  17. }

AutoComplete自动完成 - 图7

自定义选项

也可以直接传 AutoComplete.Option 作为 AutoCompletechildren,而非使用 options

TypeScript

JavaScript

AutoComplete自动完成 - 图8

  1. import React, { useState } from 'react';
  2. import { AutoComplete } from 'antd';
  3. const { Option } = AutoComplete;
  4. const Complete: React.FC = () => {
  5. const [result, setResult] = useState<string[]>([]);
  6. const handleSearch = (value: string) => {
  7. let res: string[] = [];
  8. if (!value || value.indexOf('@') >= 0) {
  9. res = [];
  10. } else {
  11. res = ['gmail.com', '163.com', 'qq.com'].map(domain => `${value}@${domain}`);
  12. }
  13. setResult(res);
  14. };
  15. return (
  16. <AutoComplete style={{ width: 200 }} onSearch={handleSearch} placeholder="input here">
  17. {result.map((email: string) => (
  18. <Option key={email} value={email}>
  19. {email}
  20. </Option>
  21. ))}
  22. </AutoComplete>
  23. );
  24. };
  25. ReactDOM.render(<Complete />, mountNode);

AutoComplete自动完成 - 图9

不区分大小写

不区分大小写的 AutoComplete

TypeScript

JavaScript

AutoComplete自动完成 - 图10

  1. import { AutoComplete } from 'antd';
  2. const options = [
  3. { value: 'Burns Bay Road' },
  4. { value: 'Downing Street' },
  5. { value: 'Wall Street' },
  6. ];
  7. const Complete: React.FC = () => (
  8. <AutoComplete
  9. style={{ width: 200 }}
  10. options={options}
  11. placeholder="try to type `b`"
  12. filterOption={(inputValue, option) =>
  13. option!.value.toUpperCase().indexOf(inputValue.toUpperCase()) !== -1
  14. }
  15. />
  16. );
  17. ReactDOM.render(<Complete />, mountNode);

AutoComplete自动完成 - 图11

查询模式 - 不确定类目

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

TypeScript

JavaScript

AutoComplete自动完成 - 图12

  1. import React, { useState } from 'react';
  2. import { Input, AutoComplete } from 'antd';
  3. import { SelectProps } from 'antd/es/select';
  4. function getRandomInt(max: number, min: number = 0) {
  5. return Math.floor(Math.random() * (max - min + 1)) + min; // eslint-disable-line no-mixed-operators
  6. }
  7. const searchResult = (query: string) =>
  8. new Array(getRandomInt(5))
  9. .join('.')
  10. .split('.')
  11. .map((_, idx) => {
  12. const category = `${query}${idx}`;
  13. return {
  14. value: category,
  15. label: (
  16. <div
  17. style={{
  18. display: 'flex',
  19. justifyContent: 'space-between',
  20. }}
  21. >
  22. <span>
  23. Found {query} on{' '}
  24. <a
  25. href={`https://s.taobao.com/search?q=${query}`}
  26. target="_blank"
  27. rel="noopener noreferrer"
  28. >
  29. {category}
  30. </a>
  31. </span>
  32. <span>{getRandomInt(200, 100)} results</span>
  33. </div>
  34. ),
  35. };
  36. });
  37. const Complete: React.FC = () => {
  38. const [options, setOptions] = useState<SelectProps<object>['options']>([]);
  39. const handleSearch = (value: string) => {
  40. setOptions(value ? searchResult(value) : []);
  41. };
  42. const onSelect = (value: string) => {
  43. console.log('onSelect', value);
  44. };
  45. return (
  46. <AutoComplete
  47. dropdownMatchSelectWidth={252}
  48. style={{ width: 300 }}
  49. options={options}
  50. onSelect={onSelect}
  51. onSearch={handleSearch}
  52. >
  53. <Input.Search size="large" placeholder="input here" enterButton />
  54. </AutoComplete>
  55. );
  56. };
  57. ReactDOM.render(<Complete />, mountNode);

API

参数说明类型默认值版本
allowClear支持清除booleanfalse
autoFocus自动获取焦点booleanfalse
backfill使用键盘选择选项的时候把选中项回填到输入框中booleanfalse
children (自动完成的数据源)自动完成的数据源React.ReactElement<OptionProps> | Array<React.ReactElement<OptionProps>>-
children (自定义输入框)自定义输入框HTMLInputElement | HTMLTextAreaElement | React.ReactElement<InputProps><Input />
defaultActiveFirstOption是否默认高亮第一个选项booleantrue
defaultOpen是否默认展开下拉菜单boolean-
defaultValue指定默认选中的条目string-
disabled是否禁用booleanfalse
dropdownClassName下拉菜单的 className 属性string-
dropdownMatchSelectWidth下拉菜单和选择器同宽。默认将设置 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-
value指定当前选中的条目string-
onBlur失去焦点时的回调function()-
onChange选中 option,或 input 的 value 变化时,调用此函数function(value)-
onDropdownVisibleChange展开下拉菜单的回调function(open)-
onFocus获得焦点时的回调function()-
onSearch搜索补全项的时候调用function(value)-
onSelect被选中时调用,参数为选中项的 value 值function(value, option)-

方法

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

FAQ

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

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

相关 issue:#18230 #17916

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

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

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

v3

  1. dataSource = ['light', 'bamboo'];
  2. // or
  3. dataSource = [
  4. { value: 'light', text: 'Light' },
  5. { value: 'bamboo', text: 'Bamboo' },
  6. ];

v4

  1. options = [
  2. { value: 'light', label: 'Light' },
  3. { value: 'bamboo', label: 'Bamboo' },
  4. ];