AutoComplete 自动完成

输入框自动填充。

使用场景

用于对输入框提供输入建议，进行自动补全的操作

与可搜索的 Select 组件的区别：

• AutoComplete 本质上是一个增强型的提供了输入建议的 Input 组件，而 Select 是一个选择器
• 点击展开时，Select 会将输入框的值全部清空，而 AutoComplete 会保留上次选中的值
• Select 的已选项渲染（renderSelectedItem）可定制化程度更高，可以为任意类型的 ReactNode，而 AutoComplete 只允许为字符串

代码演示

如何引入

import { AutoComplete } from '@kousum/semi-ui-vue';

基本用法

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

0px x 0px

baseAutoComplete.vue

tsconfig.json

Import Map

xxxxxxxxxx

40

 

1

<template>

2

  <div>

3

    <AutoComplete

4

      :data="stringData"

5

      :value="value"

6

      show-clear

7

      :prefix="h(IconSearch)"

8

      placeholder="搜索... "

9

      @search="handleStringSearch"

10

      @change="handleChange"

11

      :style="{ width: '200px' }"

12

    />

13

  </div>

14

</template>

15

​

16

<script setup>

17

import { ref, h } from 'vue';

18

import { AutoComplete } from '@kousum/semi-ui-vue';

19

import { IconSearch } from '@kousum/semi-icons-vue';

20

​

21

const stringData = ref([]);

22

const value = ref('');

23

​

24

const handleStringSearch = (value) => {

25

  let result;

26

  if (value) {

27

    result = ['gmail.com', '163.com', 'qq.com'].map(domain => `${value}@${domain}`);

Show Error

Auto Save

自定义候选项渲染

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

0px x 0px

diyItemAutoComplete.vue

tsconfig.json

Import Map

xxxxxxxxxx

11

 

1

<template>

2

  <AutoComplete

3

    :data="data"

4

    show-clear

5

    :prefix="h(IconSearch)"

6

    @search="handleStringSearch"

7

    placeholder="搜索... "

8

    :render-item="renderOption"

9

    :render-selected-item="(option) => option.email"

10

    style="width: 280px"

11

  />

12

</template>

13

​

14

<script setup lang="tsx">

15

import { ref, h } from 'vue';

16

import { AutoCompleteFunc, Avatar } from '@kousum/semi-ui-vue';

17

import { IconSearch } from '@kousum/semi-icons-vue';

18

const AutoComplete = AutoCompleteFunc<{ name: string; email: string; abbr: string; color: string }>();

19

const color = ['amber', 'indigo', 'cyan'];

20

const data = ref([

21

  { name: '夏可漫', email: 'xiakeman@example.com', abbr: 'XK', color: 'amber' },

22

  { name: '申悦', email: 'shenyue@example.com', abbr: 'SY', color: 'indigo' },

23

  { name: '曲晨一', email: 'quchenyi@example.com', abbr: 'CY', color: 'blue' },

24

  { name: '文嘉茂', email: 'wenjiamao@example.com', abbr: 'JM', color: 'cyan' },

25

]);

26

const value = ref('');

Show Error

Auto Save

远程搜索

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

0px x 0px

remoteAutoComplete.vue

tsconfig.json

Import Map

xxxxxxxxxx

11

 

1

<template>

2

  <AutoComplete

3

    :data="list"

4

    style="width: 250px"

5

    :prefix="h(IconSearch)"

6

    @search="search"

7

    :loading="loading"

8

    :renderItem="renderItem"

9

    :renderSelectedItem="renderSelectedItem"

10

    @select="handleSelect"

11

  ></AutoComplete>

12

</template>

13

​

14

<script setup lang="tsx">

15

import { ref, reactive, onMounted, h } from 'vue';

16

import { AutoComplete } from '@kousum/semi-ui-vue';

17

import { IconSearch } from '@kousum/semi-icons-vue';

18

import { IconSelect, IconForm, IconTable, IconInput, IconButton } from '@kousum/semi-icons-lab-vue';

19

import lodash from 'lodash';

20

​

21

​

22

let initList = [

23

  { value: 'select', label: '选择器', icon: h(IconSelect) },

24

  { value: 'input', label: '输入框', icon: h(IconInput) },

25

  { value: 'form', label: '表单', icon: h(IconForm) },

26

  { value: 'button', label: '按钮', icon: h(IconButton) },

Show Error

Auto Save

尺寸

通过设置 size 可设置输入框尺寸，可选small，default(默认)，large

0px x 0px

sizeAutoComplete.vue

tsconfig.json

Import Map

xxxxxxxxxx

35

 

1

<template>

2

  <div>

3

    <div>

4

      <AutoComplete

5

        :data="[1, 2, 3, 4]"

6

        size="small"

7

        placeholder="small"

8

        :style="{ width: '200px' }"

9

      ></AutoComplete>

10

      <br />

11

      <br />

12

      <AutoComplete

13

        :data="[1, 2, 3, 4]"

14

        size="default"

15

        placeholder="default"

16

        :style="{ width: '200px' }"

17

      ></AutoComplete>

18

      <br />

19

      <br />

20

      <AutoComplete

21

        :data="[1, 2, 3, 4]"

22

        size="large"

23

        placeholder="large"

24

        :style="{ width: '200px' }"

25

      ></AutoComplete>

26

    </div>

27

  </div>

28

</template>

Show Error

Auto Save

下拉菜单的位置

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

0px x 0px

positionAutoComplete.vue

tsconfig.json

Import Map

xxxxxxxxxx

37

 

1

<template>

2

  <div style="padding-top: 120px">

3

    <AutoComplete

4

      :data="data"

5

      position="top"

6

      @search="change"

7

      placeholder="选项菜单在上方显示"

8

      style="width: 200px; margin: 10px;"

9

    ></AutoComplete>

10

    <AutoComplete

11

      :data="data"

12

      position="rightTop"

13

      @search="change"

14

      placeholder="选项菜单在右侧显示"

15

      style="width: 200px; margin: 10px;"

16

    ></AutoComplete>

17

  </div>

18

</template>

19

​

20

<script setup>

21

import { ref } from 'vue';

22

import { AutoComplete } from '@kousum/semi-ui-vue';

23

​

24

const data = ref([]);

25

​

26

const change = (input) => {

27

  let newData = ['gmail.com', '163.com', 'qq.com'].map(domain => `${input}@${domain}`);

28

  if (!input) {

Show Error

Auto Save

禁用

0px x 0px

disabledAutoComplete.vue

tsconfig.json

Import Map

xxxxxxxxxx

18

 

1

<template>

2

  <div>

3

    <div>

4

      <AutoComplete

5

        :data="[1, 2, 3, 4]"

6

        placeholder="禁用下拉菜单"

7

        :style="{ width: '200px' }"

8

        :disabled="true"

9

      ></AutoComplete>

10

    </div>

11

  </div>

12

</template>

13

​

14

<script setup>

15

import { AutoComplete } from '@kousum/semi-ui-vue';

16

</script>

17

​

18

​

Show Error

Auto Save

校验状态

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

0px x 0px

statusAutoComplete.vue

tsconfig.json

Import Map

xxxxxxxxxx

28

 

1

<template>

2

  <div>

3

    <AutoComplete

4

      defaultValue="ies"

5

      validateStatus="warning"

6

      :style="{ width: '200px' }"

7

    />

8

    <br />

9

    <br />

10

    <AutoComplete

11

      defaultValue="ies"

12

      validateStatus="error"

13

      :style="{ width: '200px' }"

14

    />

15

    <br />

16

    <br />

17

    <AutoComplete

18

      defaultValue="ies"

19

      :style="{ width: '200px' }"

20

    />

21

  </div>

22

</template>

23

​

24

<script setup>

25

import { AutoComplete } from '@kousum/semi-ui-vue';

26

</script>

27

​

28

​

Show Error

Auto Save

自定义空内容

可设置自定义展示空内容

0px x 0px

emptyAutoComplete.vue

tsconfig.json

Import Map

xxxxxxxxxx

11

 

1

<template>

2

  <AutoComplete

3

    :loading="loading"

4

    :data="data"

5

    :empty-content="emptyContent"

6

    placeholder="自定义空内容"

7

    :style="{ width: '200px' }"

8

    @search="fetchData"

9

  />

10

</template>

11

​

12

<script setup lang="tsx">

13

import { ref, onMounted } from 'vue';

14

import { AutoComplete, Empty } from '@kousum/semi-ui-vue';

15

import { IllustrationNoContent } from '@kousum/semi-illustrations-vue';

16

​

17

const data = ref([]);

18

const loading = ref(false);

19

​

20

const fetchData = (v) => {

21

  loading.value = true;

22

  setTimeout(() => {

23

    if (!v) {

24

      data.value = [];

25

      loading.value = false;

26

      return;

Show Error

Auto Save

API 参考

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

Accessibility

键盘和焦点

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

文案规范

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

设计变量

spacing

color

width

radius

font

animation

变量	默认值	用法
$spacing-autoComplete_loading_wrapper-paddingTop	$spacing-tight	加载搜索结果时的顶部内边距
$spacing-autoComplete_loading_wrapper-paddingBottom	$spacing-tight	加载搜索结果时的底部内边距
$spacing-autoComplete_option_tick-marginRight	$spacing-tight	自动完成菜单选中对勾右侧外边距
$spacing-autoComplete_option-paddingLeft	$spacing-base-tight	自动完成菜单项左侧内边距
$spacing-autoComplete_option-paddingRight	$spacing-base-tight	自动完成菜单项右侧内边距
$spacing-autoComplete_option-paddingTop	$spacing-tight	自动完成菜单项顶部内边距
$spacing-autoComplete_option-paddingBottom	$spacing-tight	自动完成菜单项底部内边距
$spacing-autoComplete_option_first-marginTop	$spacing-extra-tight	自动完成第一个菜单项顶部外边距
$spacing-autoComplete_option_last-marginBottom	$spacing-extra-tight	自动完成最后一个菜单项顶部外边距
$spacing-autoComplete_option_list-paddingTop	0px	自动完成内容区顶部内边距

显示第 1 条-第 10 条，共 13 条

• 1
• 2

变量	默认值	用法
$color-autoComplete_option_keyword-text	var(--semi-color-primary)	自动完成菜单选项匹配搜索结果文本颜色
$color-autoComplete_option-bg-default	transparent	自动完成菜单选项背景颜色 - 默认态
$color-autoComplete_option-icon-default	transparent	自动完成菜单选项图标颜色 - 默认态
$color-autoComplete_option-bg-hover	var(--semi-color-fill-0)	自动完成菜单选项背景颜色 - 悬停态
$color-autoComplete_option-bg-active	var(--semi-color-fill-1)	自动完成菜单选项背景颜色 - 按下态
$color-autoComplete_option_disabled-text	var(--semi-color-disabled-text)	禁用自动完成菜单选项文字颜色
$color-autoComplete_option_disabled-bg	transparent	禁用自动完成菜单选项背景颜色
$color-autoComplete_option-icon-active	var(--semi-color-text-2)	禁用自动完成菜单选项图标颜色 - 选中态
$color-autoComplete_option-border-default	var(--semi-color-border)	分组自动完成菜单项描边颜色
$color-autoComplete_option_main-text	var(--semi-color-text-0)	自动完成菜单选项文本颜色

显示第 1 条-第 10 条，共 18 条

• 1
• 2

变量	默认值	用法
$width-autoComplete_option_tick	$width-icon-small	自动完成菜单项选中对勾图标大小

显示第 1 条-第 1 条，共 1 条

• 1

变量	默认值	用法
$radius-autoComplete_option	0px	自动完成待选项圆角

显示第 1 条-第 1 条，共 1 条

• 1

变量	默认值	用法
$font-autoComplete-fontWeight	$font-weight-regular	自动完成文本字重
$font-autoComplete_inset_label-fontWeight	600	自动完成内嵌标签文本字重
$font-autoComplete_keyword-fontWeight	600	自动完成搜索结果命关键词中文本字重

显示第 1 条-第 3 条，共 3 条

• 1

变量	默认值	用法
$transition_duration-autoComplete_option-bg	var(--semi-transition_duration-none)	选择器-选项-动画持续时间
$transition_function-autoComplete_option-bg	var(--semi-transition_function-easeIn)	选择器-选项-过渡曲线
$transition_delay-autoComplete_option-bg	var(--semi-transition_delay-none)	选择器-选项-延迟时间

显示第 1 条-第 3 条，共 3 条

• 1