FxAutocomplete 自动补全输入框

根据当前输入获取推荐建议。不依赖任何 UI 框架，继承 FxInput 全部能力，内部组合 FxTooltip + FxScrollbar + FxIcon。

基础用法

fetch-suggestions 是返回建议的方法。本例中 querySearch(queryString, cb) 在建议就绪时通过 cb(data) 回传；第二个示例关闭 trigger-on-focus，仅输入时才出建议。

<template>
  <div class="demo-autocomplete">
    <div class="demo-block">
      <div class="demo-title">激活时展示建议（默认）</div>
      <FxAutocomplete
        v-model="state1"
        :fetch-suggestions="querySearch"
        clearable
        placeholder="请输入"
        @select="handleSelect"
      />
    </div>
    <div class="demo-block">
      <div class="demo-title">仅输入时展示建议</div>
      <FxAutocomplete
        v-model="state2"
        :fetch-suggestions="querySearch"
        :trigger-on-focus="false"
        clearable
        placeholder="请输入"
        @select="handleSelect"
      />
    </div>
  </div>
</template>

<script setup lang="ts">
import { onMounted, ref } from "vue"

interface RestaurantItem {
  value: string
  link: string
}

const state1 = ref("")
const state2 = ref("")
const restaurants = ref<RestaurantItem[]>([])

const querySearch = (
  queryString: string,
  cb: (data: RestaurantItem[]) => void,
) => {
  const results = queryString
    ? restaurants.value.filter(createFilter(queryString))
    : restaurants.value
  cb(results)
}
const createFilter = (queryString: string) => (item: RestaurantItem) =>
  item.value.toLowerCase().indexOf(queryString.toLowerCase()) === 0

const loadAll = (): RestaurantItem[] => [
  { value: "vue", link: "https://github.com/vuejs/core" },
  { value: "vue-router", link: "https://github.com/vuejs/router" },
  { value: "pinia", link: "https://github.com/vuejs/pinia" },
  { value: "element", link: "https://github.com/ElemeFE/element" },
  { value: "cooking", link: "https://github.com/ElemeFE/cooking" },
  { value: "mint-ui", link: "https://github.com/ElemeFE/mint-ui" },
  { value: "vuex", link: "https://github.com/vuejs/vuex" },
  { value: "babel", link: "https://github.com/babel/babel" },
]

const handleSelect = (item: Record<string, any>) => {
  console.log(item)
}

onMounted(() => {
  restaurants.value = loadAll()
})
</script>

<style scoped>
.demo-autocomplete {
  display: flex;
  flex-wrap: wrap;
  gap: 2rem;
}
.demo-block {
  display: flex;
  flex-direction: column;
  gap: 0.5rem;
}
.demo-title {
  font-size: 0.875rem;
  color: var(--fx-text-color-secondary, #909399);
  min-height: 2.5em;
  display: flex;
  align-items: center;
}
@media screen and (max-width: 768px) {
  .demo-autocomplete {
    gap: 1rem;
  }
  .demo-block {
    width: 100%;
  }
}
</style>

自定义模板

用作用域插槽自定义建议项，作用域内通过 item 访问建议对象。

<template>
  <FxAutocomplete
    v-model="state"
    :fetch-suggestions="querySearch"
    popper-class="demo-autocomplete-template"
    placeholder="请输入"
    @select="handleSelect"
  >
    <template #suffix>
      <FxIcon name="ep:edit" @click="handleIconClick" />
    </template>
    <template #default="{ item }">
      <div class="value">{{ item.value }}</div>
      <span class="link">{{ item.link }}</span>
    </template>
  </FxAutocomplete>
</template>

<script setup lang="ts">
import { onMounted, ref } from "vue"

interface LinkItem {
  value: string
  link: string
}

const state = ref("")
const links = ref<LinkItem[]>([])

const querySearch = (
  queryString: string,
  cb: (data: LinkItem[]) => void,
) => {
  const results = queryString
    ? links.value.filter(createFilter(queryString))
    : links.value
  cb(results)
}
const createFilter = (queryString: string) => (item: LinkItem) =>
  item.value.toLowerCase().indexOf(queryString.toLowerCase()) === 0

const loadAll = (): LinkItem[] => [
  { value: "vue", link: "https://github.com/vuejs/core" },
  { value: "vue-router", link: "https://github.com/vuejs/router" },
  { value: "pinia", link: "https://github.com/vuejs/pinia" },
  { value: "element", link: "https://github.com/ElemeFE/element" },
  { value: "cooking", link: "https://github.com/ElemeFE/cooking" },
  { value: "mint-ui", link: "https://github.com/ElemeFE/mint-ui" },
  { value: "vuex", link: "https://github.com/vuejs/vuex" },
  { value: "babel", link: "https://github.com/babel/babel" },
]

const handleSelect = (item: Record<string, any>) => {
  console.log(item)
}
const handleIconClick = (ev: Event) => {
  console.log(ev)
}

onMounted(() => {
  links.value = loadAll()
})
</script>

<style scoped>
.value {
  font-weight: 500;
  line-height: normal;
}
.link {
  display: block;
  font-size: 12px;
  color: var(--fx-text-color-secondary, #909399);
}
</style>

<style>
/* popper teleport 到 body，需全局样式（唯一类名避免污染） */
.demo-autocomplete-template li {
  line-height: normal;
  padding: 7px;
}
</style>

远程搜索

从服务端异步搜索数据。

<template>
  <FxAutocomplete
    v-model="state"
    :fetch-suggestions="querySearchAsync"
    placeholder="请输入"
    @select="handleSelect"
  />
</template>

<script setup lang="ts">
import { onMounted, ref } from "vue"

interface LinkItem {
  value: string
  link: string
}

const state = ref("")
const links = ref<LinkItem[]>([])

const loadAll = (): LinkItem[] => [
  { value: "vue", link: "https://github.com/vuejs/core" },
  { value: "vue-router", link: "https://github.com/vuejs/router" },
  { value: "pinia", link: "https://github.com/vuejs/pinia" },
  { value: "element", link: "https://github.com/ElemeFE/element" },
  { value: "cooking", link: "https://github.com/ElemeFE/cooking" },
  { value: "mint-ui", link: "https://github.com/ElemeFE/mint-ui" },
  { value: "vuex", link: "https://github.com/vuejs/vuex" },
  { value: "babel", link: "https://github.com/babel/babel" },
]

let timeout: ReturnType<typeof setTimeout>
const querySearchAsync = (
  queryString: string,
  cb: (data: LinkItem[]) => void,
) => {
  const results = queryString
    ? links.value.filter(createFilter(queryString))
    : links.value

  clearTimeout(timeout)
  timeout = setTimeout(() => {
    cb(results)
  }, 3000 * Math.random())
}
const createFilter = (queryString: string) => (item: LinkItem) =>
  item.value.toLowerCase().indexOf(queryString.toLowerCase()) === 0

const handleSelect = (item: Record<string, any>) => {
  console.log(item)
}

onMounted(() => {
  links.value = loadAll()
})
</script>

自定义 loading

通过 loading 插槽覆盖加载内容。

<template>
  <div class="demo-autocomplete">
    <div class="demo-block">
      <div class="demo-title">自定义 loading 图标</div>
      <FxAutocomplete
        v-model="state"
        :fetch-suggestions="querySearchAsync"
        placeholder="请输入"
        @select="handleSelect"
      >
        <template #loading>
          <FxIcon name="ep:loading" class="custom-loading-icon" />
        </template>
      </FxAutocomplete>
    </div>
    <div class="demo-block">
      <div class="demo-title">自定义 loading 文案</div>
      <FxAutocomplete
        v-model="state"
        :fetch-suggestions="querySearchAsync"
        placeholder="请输入"
        @select="handleSelect"
      >
        <template #loading>
          <span class="custom-loading-text">加载中…</span>
        </template>
      </FxAutocomplete>
    </div>
  </div>
</template>

<script setup lang="ts">
import { onMounted, ref } from "vue"

interface LinkItem {
  value: string
  link: string
}

const state = ref("")
const links = ref<LinkItem[]>([])

const loadAll = (): LinkItem[] => [
  { value: "vue", link: "https://github.com/vuejs/core" },
  { value: "vue-router", link: "https://github.com/vuejs/router" },
  { value: "pinia", link: "https://github.com/vuejs/pinia" },
  { value: "element", link: "https://github.com/ElemeFE/element" },
  { value: "cooking", link: "https://github.com/ElemeFE/cooking" },
  { value: "mint-ui", link: "https://github.com/ElemeFE/mint-ui" },
  { value: "vuex", link: "https://github.com/vuejs/vuex" },
  { value: "babel", link: "https://github.com/babel/babel" },
]

let timeout: ReturnType<typeof setTimeout>
const querySearchAsync = (
  queryString: string,
  cb: (data: LinkItem[]) => void,
) => {
  const results = queryString
    ? links.value.filter(createFilter(queryString))
    : links.value

  clearTimeout(timeout)
  timeout = setTimeout(() => {
    cb(results)
  }, 5000 * Math.random())
}
const createFilter = (queryString: string) => (item: LinkItem) =>
  item.value.toLowerCase().indexOf(queryString.toLowerCase()) === 0

const handleSelect = (item: Record<string, any>) => {
  console.log(item)
}

onMounted(() => {
  links.value = loadAll()
})
</script>

<style scoped>
.demo-autocomplete {
  display: flex;
  flex-wrap: wrap;
  gap: 2rem;
}
.demo-block {
  display: flex;
  flex-direction: column;
  gap: 0.5rem;
}
.demo-title {
  font-size: 0.875rem;
  color: var(--fx-text-color-secondary, #909399);
  min-height: 2.5em;
  display: flex;
  align-items: center;
}
.custom-loading-icon {
  font-size: 24px;
  color: var(--fx-color-primary, #409eff);
}
.custom-loading-text {
  font-size: 14px;
  color: var(--fx-text-color-secondary, #909399);
}
@media screen and (max-width: 768px) {
  .demo-autocomplete {
    gap: 1rem;
  }
  .demo-block {
    width: 100%;
  }
}
</style>

自定义 header / footer

通过 header / footer 插槽自定义下拉的头部和底部。

<template>
  <div class="demo-header-footer">
    <div>
      <p>自定义 header</p>
      <FxAutocomplete
        v-model="headerState"
        :fetch-suggestions="querySearchAsync"
        placeholder="请输入"
        @select="handleSelect"
      >
        <template #header>下拉头部内容</template>
      </FxAutocomplete>
    </div>
    <div>
      <p>自定义 footer</p>
      <FxAutocomplete
        ref="footerRef"
        v-model="footerState"
        :fetch-suggestions="querySearchAsync"
        placeholder="请输入"
        @select="handleSelect"
      >
        <template #footer>
          <FxBtn size="small" @click="handleClear">清空</FxBtn>
        </template>
      </FxAutocomplete>
    </div>
  </div>
</template>

<script setup lang="ts">
import { onMounted, ref } from "vue"
import type { FxAutocompleteInstance } from "@fx/components"

interface LinkItem {
  value: string
  link: string
}

const headerState = ref("")
const footerState = ref("")
const footerRef = ref<FxAutocompleteInstance>()
const links = ref<LinkItem[]>([])

const loadAll = (): LinkItem[] => [
  { value: "vue", link: "https://github.com/vuejs/core" },
  { value: "vue-router", link: "https://github.com/vuejs/router" },
  { value: "pinia", link: "https://github.com/vuejs/pinia" },
  { value: "element", link: "https://github.com/ElemeFE/element" },
  { value: "cooking", link: "https://github.com/ElemeFE/cooking" },
  { value: "mint-ui", link: "https://github.com/ElemeFE/mint-ui" },
  { value: "vuex", link: "https://github.com/vuejs/vuex" },
  { value: "babel", link: "https://github.com/babel/babel" },
]

let timeout: ReturnType<typeof setTimeout>
const querySearchAsync = (
  queryString: string,
  cb: (data: LinkItem[]) => void,
) => {
  const results = queryString
    ? links.value.filter(createFilter(queryString))
    : links.value

  clearTimeout(timeout)
  timeout = setTimeout(() => {
    cb(results)
  }, 3000 * Math.random())
}
const createFilter = (queryString: string) => (item: LinkItem) =>
  item.value.toLowerCase().indexOf(queryString.toLowerCase()) === 0

const handleSelect = (item: Record<string, any>) => {
  console.log(item)
}

const handleClear = () => {
  footerState.value = ""
  footerRef.value?.getData()
}

onMounted(() => {
  links.value = loadAll()
})
</script>

<style scoped>
.demo-header-footer {
  display: flex;
}
.demo-header-footer > div {
  flex: 1;
  text-align: center;
}
.demo-header-footer > div > :deep(.fx-autocomplete) {
  width: 80%;
  margin: 0 auto;
}
.demo-header-footer > div:not(:last-child) {
  border-right: 1px solid var(--fx-border-color, #dcdfe6);
}
p {
  margin: 0 0 0.75rem;
  color: var(--fx-text-color-secondary, #909399);
  font-size: 0.875rem;
}
</style>

API

Attributes

属性	说明	类型	默认值
model-value (v-model)	绑定值	string / number	''
value-key	建议对象用于显示的键名	string	'value'
debounce	输入防抖延时（ms）	number	300
placement	下拉位置	'top' / 'top-start' / 'top-end' / 'bottom' / 'bottom-start' / 'bottom-end'	'bottom-start'
fetch-suggestions	获取建议的方法：建议就绪后调 cb(data) 回传，亦可返回数组 / Promise	((queryString: string, cb) => void) / array	—
trigger-on-focus	聚焦时是否展示建议	boolean	true
select-when-unmatched	无匹配项时回车是否仍触发 select	boolean	false
hide-loading	是否隐藏远程加载图标	boolean	false
highlight-first-item	是否默认高亮首项	boolean	false
fit-input-width	下拉宽度是否与输入框一致（默认仅最小宽度对齐）	boolean	false
loop-navigation	键盘导航是否首尾循环	boolean	true
popper-class	下拉自定义类名	string / array / object	—
popper-style	下拉自定义样式	string / CSSProperties	—
popper-options	floating-ui 参数	object	{}
show-arrow	是否显示箭头	boolean	true
teleported	下拉是否 teleport 到 body	boolean	true
append-to	下拉挂载位置	string / HTMLElement	—
placeholder	占位文本	string	—
clearable	是否显示清除按钮	boolean	false
disabled	是否禁用	boolean	false
size	尺寸	'large' / 'default' / 'small'	—
prefix-icon	前置图标（字符串为 FxIcon 图标名）	string / Component	—
suffix-icon	后置图标（字符串为 FxIcon 图标名）	string / Component	—
name	原生 name	string	—
aria-label	原生 aria-label	string	—

另继承 FxInput 其余 props（readonly / maxlength / formatter / parser 等，详见 FxInput）。

Events

事件名	说明	类型
update:modelValue	绑定值更新	(value: string | number) => void
input	输入时	(value: string | number) => void
change	值变化（失焦 / 回车等）	(value: string | number) => void
focus	聚焦	(event: FocusEvent) => void
blur	失焦	(event: FocusEvent) => void
clear	点击清除按钮	() => void
select	选中某条建议	(item: Record<string, any>) => void

Slots

插槽名	说明	类型
default	自定义建议项内容	{ item: Record<string, any> }
header	下拉顶部内容	—
footer	下拉底部内容	—
loading	自定义加载内容	—
prefix	输入框前置内容（透传 FxInput）	—
suffix	输入框后置内容（透传 FxInput）	—
prepend	输入框前置区块（透传 FxInput）	—
append	输入框后置区块（透传 FxInput）	—

Exposes

名称	说明	类型
highlightedIndex	当前高亮项索引	Ref<number>
activated	是否已激活	Ref<boolean>
loading	远程加载态	Ref<boolean>
inputRef	FxInput 实例	Ref<FxInputInstance>
popperRef	FxTooltip 实例	Ref<FxTooltipInstance>
suggestions	当前建议列表	Ref<Record<string, any>[]>
focus	聚焦输入框	() => void
blur	失焦输入框	() => void
close	关闭下拉	() => void
highlight	高亮指定索引项	(index: number) => void
handleSelect	选中某条建议	(item: any) => Promise<void>
handleKeyEnter	处理回车	() => Promise<void>
getData	拉取建议列表	(queryString: string) => Promise<void>

键盘导航

按键	行为
↑ / ↓	移动高亮
Enter / NumpadEnter	选中当前项
Esc	关闭下拉
Tab	关闭下拉
Home / End	跳到首 / 末项
PageUp / PageDown	翻 10 项