Autocomplete 自动补全输入框

根据用户输入内容提供对应的补全建议，适用于需要联想、历史记录或远程检索的场景。

import { createApp } from 'vue'
import { Autocomplete as ElAutocomplete } from '@szhn/dh-design-pc'

const app = createApp()
app.use(ElAutocomplete)

基础用法

通过 fetch-suggestions 返回建议列表。支持数组或函数两种形式，函数通过 callback(data) 异步返回结果。

<template>
  <el-autocomplete
    v-model="value"
    :fetch-suggestions="querySearch"
    placeholder="请输入内容"
    style="width: 300px"
  />
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import { Autocomplete as ElAutocomplete } from '@szhn/dh-design-pc'


const value = ref('')
const restaurants = [
  { value: 'Vue', link: 'https://vuejs.org' },
  { value: 'Element Plus', link: 'https://element-plus.org' },
  { value: 'Vite', link: 'https://vitejs.dev' },
  { value: 'Vant', link: 'https://vant-ui.github.io' },
]

function querySearch(queryString: string, cb: (results: any[]) => void) {
  const results = queryString
    ? restaurants.filter((r) => r.value.toLowerCase().includes(queryString.toLowerCase()))
    : restaurants
  cb(results)
}
</script>

自定义模板

使用默认插槽自定义每一条建议的渲染，可以展示更丰富的结构化信息。

<template>
  <el-autocomplete
    v-model="value"
    :fetch-suggestions="querySearch"
    placeholder="请输入站点名称"
    style="width: 320px"
    @select="handleSelect"
  >
    <template #default="{ item }">
      <div style="display: flex; justify-content: space-between; align-items: center;">
        <span style="font-weight: 500;">{{ item.value }}</span>
        <span style="font-size: 12px; color: var(--dh-text-color-secondary, #909399);">{{ item.link }}</span>
      </div>
    </template>
  </el-autocomplete>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import { Autocomplete as ElAutocomplete } from '@szhn/dh-design-pc'


const value = ref('')
const sites = [
  { value: 'Vue', link: 'https://vuejs.org' },
  { value: 'Element Plus', link: 'https://element-plus.org' },
  { value: 'Vite', link: 'https://vitejs.dev' },
  { value: 'Pinia', link: 'https://pinia.vuejs.org' },
]

function querySearch(queryString: string, cb: (results: any[]) => void) {
  const results = queryString
    ? sites.filter((r) => r.value.toLowerCase().includes(queryString.toLowerCase()))
    : sites
  cb(results)
}

function handleSelect(item: any) {
  console.log('selected', item)
}
</script>

远程搜索

配合防抖与后端接口实现远程检索，适合数据量较大或需要后端过滤的场景。

<template>
  <el-autocomplete
    v-model="value"
    :fetch-suggestions="queryRemote"
    placeholder="输入关键词搜索"
    :debounce="400"
    clearable
    style="width: 320px"
  />
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import { Autocomplete as ElAutocomplete } from '@szhn/dh-design-pc'


const value = ref('')
const allData = ['海口', '三亚', '琼海', '文昌', '万宁', '五指山', '儋州', '东方']

function queryRemote(queryString: string, cb: (results: any[]) => void) {
  setTimeout(() => {
    const results = allData
      .filter((item) => item.includes(queryString))
      .map((v) => ({ value: v }))
    cb(results)
  }, 300)
}
</script>

前缀 / 后缀

使用 prefix、suffix、prepend、append 插槽扩展输入框两侧的内容。

<template>
  <div style="display: flex; flex-direction: column; gap: 12px; max-width: 360px;">
    <el-autocomplete v-model="value1" :fetch-suggestions="querySearch" placeholder="带前缀图标">
      <template #prefix>
        <el-icon><Search /></el-icon>
      </template>
    </el-autocomplete>

    <el-autocomplete v-model="value2" :fetch-suggestions="querySearch" placeholder="带后置内容">
      <template #append>搜索</template>
    </el-autocomplete>
  </div>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import { Autocomplete as ElAutocomplete, Icon as ElIcon } from '@szhn/dh-design-pc'
import { Search } from '@szhn/dh-design-pc/icons'


const value1 = ref('')
const value2 = ref('')
const sites = [{ value: 'Vue' }, { value: 'Vite' }, { value: 'Pinia' }]

function querySearch(qs: string, cb: (results: any[]) => void) {
  cb(qs ? sites.filter((s) => s.value.toLowerCase().includes(qs.toLowerCase())) : sites)
}
</script>

自定义头部与底部

通过 header 和 footer 插槽定制下拉菜单的顶部与底部区域，常用于提示、分类或操作按钮。

<template>
  <el-autocomplete
    v-model="value"
    :fetch-suggestions="querySearch"
    placeholder="带头部和底部"
    style="width: 320px"
  >
    <template #header>
      <div style="padding: 4px 12px; color: var(--dh-text-color-secondary, #909399); font-size: 12px;">
        推荐关键词
      </div>
    </template>
    <template #footer>
      <div style="padding: 4px 12px; color: var(--dh-color-primary, #409eff); cursor: pointer; font-size: 12px;">
        + 新增选项
      </div>
    </template>
  </el-autocomplete>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import { Autocomplete as ElAutocomplete } from '@szhn/dh-design-pc'


const value = ref('')
const sites = [{ value: 'Vue' }, { value: 'Element Plus' }, { value: 'Vite' }]

function querySearch(qs: string, cb: (r: any[]) => void) {
  cb(qs ? sites.filter((s) => s.value.toLowerCase().includes(qs.toLowerCase())) : sites)
}
</script>

API

Attributes

属性	说明	类型	默认值
model-value / v-model	选中项绑定值	string	—
fetch-suggestions	获取建议的方法或静态数组	Array / Function	—
placeholder	占位符	string	—
trigger-on-focus	聚焦时是否触发搜索	boolean	true
debounce	搜索防抖延时（ms）	number	300
clearable	是否可清空	boolean	false
value-key	建议对象中用于显示的 key	string	value

Events

事件	说明	参数
select	选中某一建议项时触发	item
change	输入值变化时触发	value
clear	点击清空按钮时触发	—

Slots

名称	说明
default	自定义建议项渲染，作用域参数 { item }
prefix / suffix	输入框前/后图标
prepend / append	输入框前/后置内容
header / footer	下拉列表头部/底部

更多属性与用法请参考 Element Plus Autocomplete 文档。