Autocomplete 自动补全输入框

Autocomplete 根据输入内容提供对应的输入建议。VISTA B 直接使用 Element Plus 的 el-autocomplete，适合用于搜索框、表单字段和需要快速选择历史项的输入场景。

基础用法

通过 fetch-suggestions 返回建议列表。方法会收到当前输入值 queryString 和回调函数 cb，通过 cb(data) 将建议数据传回组件。默认会读取建议对象中的 value 字段作为展示文本。

list suggestions when activated

list suggestions on input

selected: 未选择

<script setup>
import { ref } from 'vue'

const state = ref('')
const suggestions = [
  { value: 'vue', link: 'https://github.com/vuejs/vue' },
  { value: 'element', link: 'https://github.com/element-plus/element-plus' }
]

const querySearch = (queryString, cb) => {
  const results = queryString
    ? suggestions.filter((item) => item.value.startsWith(queryString))
    : suggestions
  cb(results)
}
</script>

<template>
  <el-autocomplete
    v-model="state"
    :fetch-suggestions="querySearch"
    clearable
    placeholder="Please Input"
  />
</template>

自定义模板

使用默认插槽可以自定义建议项内容。插槽参数中的 item 是当前建议对象。

<el-autocomplete
  v-model="state"
  :fetch-suggestions="querySearch"
  popper-class="my-autocomplete"
  placeholder="Please input"
>
  <template #suffix>
    <el-icon class="el-input__icon">
      <Edit />
    </el-icon>
  </template>
  <template #default="{ item }">
    <div>{{ item.value }}</div>
    <span>{{ item.link }}</span>
  </template>
</el-autocomplete>

远程搜索

fetch-suggestions 可以异步返回数据，适用于从服务端搜索建议。配合 debounce 可以控制请求防抖时间。

<script setup>
import { ref } from 'vue'

const state = ref('')
let timeout

const querySearchAsync = (queryString, cb) => {
  clearTimeout(timeout)
  timeout = setTimeout(() => {
    cb([{ value: queryString || 'vue' }])
  }, 800)
}
</script>

<template>
  <el-autocomplete
    v-model="state"
    :fetch-suggestions="querySearchAsync"
    placeholder="Please input"
  />
</template>

自定义加载

通过 loading 插槽可以替换远程搜索时的加载内容。

<el-autocomplete
  v-model="state"
  :fetch-suggestions="querySearchAsync"
  placeholder="Please input"
>
  <template #loading>
    <el-icon class="is-loading">
      <Loading />
    </el-icon>
  </template>
</el-autocomplete>

自定义头部与底部

使用 header 和 footer 插槽可以在建议列表顶部或底部添加自定义内容。

Custom header content

Custom footer content

<el-autocomplete
  ref="autocompleteRef"
  v-model="state"
  :fetch-suggestions="querySearchAsync"
>
  <template #header>header content</template>
  <template #footer>
    <el-button link size="small" @click="state = ''">Clear</el-button>
  </template>
</el-autocomplete>

API

Autocomplete 属性

属性	说明	类型	默认值
model-value / v-model	选中项绑定值	string	空
placeholder	占位文本	string	空
clearable	是否可清空	boolean	false
disabled	是否禁用	boolean	false
value-key	输入建议对象中用于显示的键名	string	value
debounce	获取输入建议的防抖延时，单位为毫秒	number	300
placement	菜单弹出位置	top / top-start / top-end / bottom / bottom-start / bottom-end	bottom-start
fetch-suggestions	获取输入建议的方法或数组；函数模式需要通过 callback(data) 返回结果	array / function	空
trigger-on-focus	输入框获取焦点时是否显示建议	boolean	true
select-when-unmatched	输入没有任何匹配建议时，按下回车是否触发 select 事件	boolean	false
name	原生 input 的 name 属性	string	空
aria-label	原生 aria-label 属性	string	空
hide-loading	是否隐藏远程加载时的加载图标	boolean	false
popper-class	下拉列表的类名	string / object	空
popper-style	下拉列表的样式	string / object	空
popper-options	Popper.js 参数	object	{}
show-arrow	下拉菜单是否显示箭头	boolean	true
teleported	是否将下拉列表插入 append-to 指向的元素下	boolean	true
append-to	下拉框挂载到哪个 DOM 元素	CSSSelector / HTMLElement	空
highlight-first-item	是否默认高亮远程搜索结果的第一项	boolean	false
fit-input-width	下拉框宽度是否与输入框相同	boolean	false
loop-navigation	键盘导航是否从末尾循环到开头	boolean	true

Autocomplete 事件

事件名	说明	类型
blur	输入框失去焦点时触发	(event: FocusEvent) => void
focus	输入框获得焦点时触发	(event: FocusEvent) => void
input	输入值改变时触发	(value: string) => void
clear	点击清空按钮时触发	() => void
select	点击选中建议项时触发	(item: object) => void
change	输入值改变且失焦后触发	(value: string) => void

Autocomplete 插槽

插槽	说明
default	自定义输入建议内容，作用域参数为 { item }
header	下拉列表顶部内容
footer	下拉列表底部内容
prefix	输入框头部内容
suffix	输入框尾部内容
prepend	输入框前置内容，在 prefix 之前
append	输入框后置内容，在 suffix 之后
loading	自定义加载区域内容

Autocomplete 方法

方法名	说明	类型
focus	使 input 获取焦点	() => void
blur	使 input 失去焦点	() => void
close	折叠建议列表	() => void
highlight	在建议中高亮显示一个项目	(index: number) => void
getData	加载建议列表	() => void
handleSelect	手动触发选中建议事件	(item: object) => void
handleKeyEnter	手动触发键盘回车事件	() => void

使用提醒

建议项默认需要包含 value 字段；如果后端字段名不同，可以通过 value-key 指定展示字段。远程搜索时建议搭配 debounce，避免每次输入都立即请求。需要只在输入后展示建议时，将 trigger-on-focus 设置为 false。