更新记录

1.0.0（2026-04-24） 下载此版本

发布

平台兼容性

uni-app(4.08)

XyAutocomplete 自动补全组件

组件介绍

XyAutocomplete 是一个自动补全组件，支持本地数据匹配和远程搜索，允许滚动自动判断需要处于上方或是下方，适用于输入框自动提示、搜索建议等场景。

主要功能

• 支持本地数据匹配和远程搜索
• 自动调整下拉菜单位置（顶部或底部）
• 支持自定义建议列表样式和内容
• 支持加载状态显示
• 支持防抖优化
• 支持延迟显隐动画效果

基本用法

<template>
  <xy-autocomplete
    v-model="value"
    :fetch-suggestions="suggestions"
    @select="handleSelect"
  ></xy-autocomplete>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import XyAutocomplete from '@/components/XyCustom/XyAutocomplete/XyAutocomplete.vue';

const value = ref('');
const suggestions = ref([
  { value: 'Apple', label: '苹果' },
  { value: 'Banana', label: '香蕉' },
  { value: 'Cherry', label: '樱桃' },
  { value: 'Date', label: '枣' },
  { value: 'Elderberry', label: '接骨木莓' },
  { value: 'Fig', label: '无花果' },
  { value: 'Grape', label: '葡萄' },
  { value: 'Honeydew', label: '哈密瓜' },
  { value: 'Kiwi', label: '猕猴桃' },
  { value: 'Lemon', label: '柠檬' },
]);

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

API

Props

Events

Slots

Methods

示例代码

基础用法

<xy-autocomplete
  v-model="baseValue"
  :fetch-suggestions="suggestions"
  @select="handleSelect"
></xy-autocomplete>

插槽使用

<xy-autocomplete
  v-model="baseValue"
  :fetch-suggestions="suggestions"
  @select="handleSelect"
>
  <template #menuItem="{ item }">
    <view style="height: 100rpx; background-color: red">这是列表--{{ item.label }}</view>
  </template>
</xy-autocomplete>

远程搜索

<xy-autocomplete
  v-model="fetchValue"
  :fetch-suggestions="fetchSuggestions"
  placeholder="请输入内容"
  :search-when-input="true"
  show-fetch-loading
  @select="handleSelect"
>
</xy-autocomplete>

<script setup lang="ts">
const fetchValue = ref('');
const fetchSuggestions = (): Promise<Suggestion[]> => {
  return new Promise((resolve) => {
    setTimeout(() => {
      resolve(suggestions.value.filter((item) => item.value.includes(fetchValue.value)));
    }, 500);
  });
};
</script>

页面上自动调整位置

<xy-autocomplete
  v-model="pageScrollValue"
  :auto-position="true"
  :fetch-suggestions="suggestions"
  :menu-z-index="4"
  :page-scroll="onPageScroll"
  @select="handleSelect"
>
</xy-autocomplete>

<script setup lang="ts">
import { onPageScroll } from '@dcloudio/uni-app';
</script>

嵌套在 scroll-view 中

<scroll-view class="scroll-view" scroll-y @scroll="handleScroll">
  <view class="scroll-content">
    <view v-for="i in 10" :key="i" class="placeholder">{{ i }}. 占位内容</view>
    <xy-autocomplete
      ref="scrollAutocomplete"
      v-model="scrollValue"
      always-visible
      :auto-position="true"
      custom-class="custom-autocomplete"
      :fetch-suggestions="suggestions"
      :position="position"
      @select="handleSelect"
    />
    <view v-for="i in 20" :key="'bottom-' + i" class="placeholder">{{ i }}. 占位内容</view>
  </view>
</scroll-view>

<script setup lang="ts">
import { ref, onMounted } from 'vue';
import type { AutocompletePosition, XyAutocompleteContext } from '@/components/XyCustom/XyAutocomplete/XyAutocomplete';
import { debounce, queryRect } from '@/utils/function';

const scrollValue = ref('');
const scrollAutocomplete = ref<XyAutocompleteContext>();
const position = ref<AutocompletePosition>('bottom');

const handleScroll = debounce(() => {
  queryRect('.custom-autocomplete', false, scrollAutocomplete.value!.instance!).then((res) => {
    queryRect('.scroll-view', false).then((scrollRes) => {
      const scrollViewHeight = scrollRes.height || 0;
      const scrollViewTop = scrollRes.top || 0;
      const topDistance = res.top! - scrollViewTop;
      const topPositionDistance = scrollViewHeight / 3;
      const bottomPositionDistance = topPositionDistance * 2;
      if (topDistance > topPositionDistance) {
        position.value = 'top';
      } else if (topDistance < bottomPositionDistance) {
        position.value = 'bottom';
      }
    });
  });
}, 100);

onMounted(() => {
  scrollAutocomplete.value?.handleInit();
});
</script>

注意事项

1. 自动调整位置：当设置 autoPosition 为 true 时，需要传入 pageScroll 函数，以便组件能够监听页面滚动并自动调整位置。

2. 远程搜索：当设置 searchWhenInput 为 true 时，每次输入都会触发 fetchSuggestions 函数，适用于远程搜索场景。

3. 防抖优化：组件内部对输入和搜索进行了防抖处理，可以通过 fetchDebounce 和 matchDebounce 调整防抖时间。

4. 高度异常：如果在 popup 之类的组件中使用，高度可能会异常，此时需要等待 popup 弹出后再执行 handleInit 方法。

5. 多个自动补全：当页面中有多个自动补全组件时，建议设置 custom-class，以便获取正确的元素。

类型定义

// 自动补全数据类型
export type AutocompleteData = Array<{
  disabled?: boolean;
  [key: string]: any;
}>;

// 获取建议列表的函数类型
export type FetchSuggestions = (() => Promise<AutocompleteData> | AutocompleteData) | AutocompleteData;

// 自动补全位置类型
export type AutocompletePosition = 'bottom' | 'top';

// 滚动参数类型
interface Params {
  scrollTop: number;
  [key: string]: any;
}

// 滚动函数类型
export type AutocompleteOnScroll = (params: Params) => void;

// 组件上下文类型
export interface XyAutocompleteContext {
  /** 初始化，如果列表的高度异常可以执行这个 */
  handleInit: () => void;
  /** 执行匹配函数 */
  handleFetch: () => Promise<void>;
  instance: ComponentInternalInstance;
}