Autocomplete

Autocomplete — это компонент библиотеки Element Plus для создания полей ввода с динамическими подсказками. Он позволяет отображать список предложений на основе введённого текста, обеспечивая удобство поиска и выбора элементов.

Основные свойства

  • model-value Связывает значение ввода с переменной во Vue через v-model. Любое изменение в поле автоматически обновляет переменную.

  • placeholder Текст-заполнитель, отображаемый в поле, когда оно пустое.

  • fetch-suggestions Функция, которая принимает введённое значение и возвращает массив предложений. Может быть асинхронной, что удобно для запросов к API.

  • trigger-on-focus Булево значение, определяющее, показывать ли подсказки сразу при фокусе на поле.

  • debounce Задержка в миллисекундах перед вызовом функции fetch-suggestions, предотвращающая слишком частые обновления списка.

  • value-key Определяет ключ объекта, который будет использоваться для отображения значения в списке, если предложения представлены объектами.

Основные события

  • select Срабатывает при выборе одного из предложений. Возвращает выбранный элемент.

  • change Срабатывает при изменении значения в поле ввода.

  • focus и blur Стандартные события фокусировки и потери фокуса.

  • clear Активируется при очистке поля, если включена опция clearable.

Пример базового использования

<template>
  <el-autocomplete
    v-model="search"
    :fetch-suggestions="querySearch"
    placeholder="Введите название"
    @select="handleSelect"
  ></el-autocomplete>
</template>

<script>
export default {
  data() {
    return {
      search: '',
      suggestions: [
        'Apple',
        'Banana',
        'Orange',
        'Grape',
        'Mango'
      ]
    }
  },
  methods: {
    querySearch(queryString, cb) {
      const results = this.suggestions.filter(item => {
        return item.toLowerCase().includes(queryString.toLowerCase())
      })
      cb(results)
    },
    handleSelect(item) {
      console.log('Выбран:', item)
    }
  }
}
</script>

В этом примере querySearch фильтрует массив строк по введённому тексту, а событие select выводит выбранный элемент в консоль.

Работа с объектами

Autocomplete поддерживает предложения в виде объектов. Для этого используется свойство value-key.

<template>
  <el-autocomplete
    v-model="selected"
    :fetch-suggestions="querySearch"
    placeholder="Выберите пользователя"
    value-key="name"
    @select="handleSelect"
  ></el-autocomplete>
</template>

<script>
export default {
  data() {
    return {
      selected: '',
      users: [
        { id: 1, name: 'Alice' },
        { id: 2, name: 'Bob' },
        { id: 3, name: 'Charlie' }
      ]
    }
  },
  methods: {
    querySearch(queryString, cb) {
      const results = this.users.filter(user => {
        return user.name.toLowerCase().includes(queryString.toLowerCase())
      })
      cb(results)
    },
    handleSelect(item) {
      console.log('Выбран пользователь:', item)
    }
  }
}
</script>

С помощью value-key компонент отображает текстовое поле из объекта, при этом весь объект передаётся при выборе.

Асинхронные подсказки

Для интеграции с внешними API можно использовать асинхронные функции:

async function querySearchAsync(queryString, cb) {
  const response = await fetch(`https://api.example.com/search?q=${queryString}`)
  const data = await response.json()
  cb(data.items)
}

Настройка внешнего вида

  • popper-class — добавляет CSS-класс к выпадающему списку для кастомного оформления.
  • placeholder — текст внутри поля ввода.
  • highlight-first-item — автоматически выделяет первый элемент в списке предложений.

Использование с clearable и size

<el-autocomplete
  v-model="search"
  :fetch-suggestions="querySearch"
  placeholder="Поиск"
  clearable
  size="large"
></el-autocomplete>

clearable добавляет кнопку очистки поля, size регулирует размеры компонента (medium, small, large).

Кастомизация списка подсказок

Можно полностью изменить шаблон отображения элементов с помощью слота slot-scope:

<el-autocomplete
  v-model="search"
  :fetch-suggestions="querySearch"
  placeholder="Введите имя"
>
  <template #default="{ item }">
    <div style="display:flex; align-items:center;">
      <img :src="item.avatar" width="24" style="margin-right:8px;">
      <span>{{ item.name }}</span>
    </div>
  </template>
</el-autocomplete>

Такой подход позволяет добавлять аватары, иконки или дополнительную информацию для каждого предложения.

Советы по производительности

  1. Использовать debounce для уменьшения числа вызовов fetch-suggestions.
  2. Кешировать результаты при повторяющихся запросах, чтобы не обращаться к серверу каждый раз.
  3. Фильтровать данные на клиенте, если список небольшой, чтобы снизить нагрузку на API.

Интеграция с Vue 3 Composition API

import { ref } from 'vue'

export default {
  setup() {
    const search = ref('')
    const suggestions = ref(['Red', 'Green', 'Blue'])

    const querySearch = (queryString, cb) => {
      const results = suggestions.value.filter(item =>
        item.toLowerCase().includes(queryString.toLowerCase())
      )
      cb(results)
    }

    const handleSelect = (item) => {
      console.log('Выбран цвет:', item)
    }

    return { search, querySearch, handleSelect }
  }
}

Использование Composition API делает код более компактным и удобным для модульной разработки.

Autocomplete в Element Plus сочетает гибкость и удобство: от простых текстовых подсказок до кастомных списков с асинхронной загрузкой данных и полным контролем над отображением каждого элемента. Это мощный инструмент для создания интерактивных интерфейсов с поддержкой динамического поиска.

Оглавление