Автокомплиты v-autocomplete

v-autocomplete — это компонент библиотеки Vuetify, предназначенный для выбора значения из списка с возможностью поиска по введённому тексту. Он расширяет функциональность компонента v-select, добавляя динамическую фильтрацию элементов и более удобную работу с большими списками данных.

Компонент используется в ситуациях, когда список значений достаточно большой и ручной поиск необходим для ускорения выбора. При вводе текста список автоматически фильтруется, показывая только соответствующие элементы.

Основные возможности:

  • фильтрация элементов по тексту
  • поддержка одиночного и множественного выбора
  • асинхронная загрузка данных
  • возможность создавать новые элементы
  • кастомизация отображения элементов списка
  • интеграция со слотами
  • гибкая настройка поиска

Базовое использование

Минимальный пример использования v-autocomplete включает список элементов и привязку выбранного значения через v-model.

<template>
  <v-autocomplete
    v-model="selected"
    :items="items"
    label="Выберите язык"
  ></v-autocomplete>
</template>

<script>
export default {
  data() {
    return {
      selected: null,
      items: ["JavaScript", "Python", "Go", "Rust"]
    }
  }
}
</script>

В этом примере:

  • v-model хранит выбранное значение
  • items содержит массив вариантов
  • label отображает подпись поля

После выбора элемента его значение записывается в переменную selected.

Структура элементов

Элементы списка могут быть как простыми строками, так и объектами.

Простой список

items: ["Vue", "React", "Angular"]

В этом случае текст элемента используется как значение.

Список объектов

При использовании объектов требуется указать свойства, отвечающие за отображение и значение.

items: [
  { name: "Vue", id: 1 },
  { name: "React", id: 2 },
  { name: "Angular", id: 3 }
]
<v-autocomplete
  v-model="selected"
  :items="items"
  item-title="name"
  item-value="id"
  label="Фреймворк"
/>

Параметры:

Свойство Назначение
item-title поле объекта для отображения
item-value поле, используемое как значение

В результате selected будет содержать id, а пользователю отображается name.

Поиск и фильтрация

Одной из ключевых возможностей v-autocomplete является автоматическая фильтрация списка.

По умолчанию используется встроенный алгоритм поиска, который:

  • сравнивает введённый текст
  • ищет совпадения внутри строки
  • игнорирует регистр

Пример:

<v-autocomplete
  v-model="selected"
  :items="frameworks"
  label="Фреймворк"
/>

Если пользователь вводит vu, в списке остаётся Vue.

Пользовательская функция фильтрации

Иногда требуется более сложная логика поиска. Для этого используется свойство filter.

<v-autocomplete
  :items="items"
  :filter="customFilter"
  label="Поиск"
/>
methods: {
  customFilter(item, queryText, itemText) {
    return itemText.toLowerCase().startsWith(queryText.toLowerCase())
  }
}

Параметры функции:

Параметр Описание
item объект элемента
queryText введённый текст
itemText текст для отображения

Возвращаемое значение определяет, показывать элемент или нет.

Множественный выбор

Компонент поддерживает выбор нескольких значений через свойство multiple.

<v-autocomplete
  v-model="selected"
  :items="languages"
  multiple
  label="Языки программирования"
/>
selected: []

Выбранные элементы отображаются в виде чипов.

Отображение выбранных элементов

Часто используется параметр chips.

<v-autocomplete
  v-model="selected"
  :items="languages"
  multiple
  chips
  label="Выберите языки"
/>

Каждый выбранный элемент превращается в визуальный чип.

Дополнительные настройки:

Свойство Описание
closable-chips возможность удалить элемент
small-chips уменьшенный размер
clearable кнопка очистки

Асинхронная загрузка данных

При работе с API список элементов может загружаться динамически.

<v-autocomplete
  v-model="user"
  :items="users"
  :loading="loading"
  label="Пользователь"
  hide-no-data
/>
data() {
  return {
    users: [],
    loading: false
  }
}

Получение данных:

watch: {
  search(val) {
    this.loading = true

    fetch(`/api/users?q=${val}`)
      .then(res => res.json())
      .then(data => {
        this.users = data
      })
      .finally(() => {
        this.loading = false
      })
  }
}

Здесь используется свойство loading, отображающее индикатор загрузки.

Использование search-input

Чтобы отслеживать текст поиска, используется v-model:search.

<v-autocomplete
  v-model="value"
  v-model:search="search"
  :items="items"
  label="Поиск"
/>
data() {
  return {
    value: null,
    search: ""
  }
}

search содержит введённый пользователем текст.

Это полезно для:

  • запросов к серверу
  • динамической фильтрации
  • логирования

Добавление новых элементов

Иногда требуется возможность добавлять элементы, которых нет в списке.

Для этого используется combobox режим.

<v-autocomplete
  v-model="value"
  :items="items"
  label="Теги"
  multiple
  chips
  closable-chips
/>

При вводе нового текста и подтверждении он добавляется в список.

Кастомизация отображения элементов

Vuetify предоставляет слоты для полного контроля над отображением.

Слот item

<v-autocomplete
  :items="items"
  item-title="name"
>
  <template v-slot:item="{ props, item }">
    <v-list-item v-bind="props">
      <v-list-item-title>
        {{ item.raw.name }}
      </v-list-item-title>
      <v-list-item-subtitle>
        {{ item.raw.description }}
      </v-list-item-subtitle>
    </v-list-item>
  </template>
</v-autocomplete>

Это позволяет отображать дополнительные данные.

Кастомизация выбранных элементов

Используется слот selection.

<template v-slot:selection="{ item }">
  <v-chip>
    {{ item.raw.name }}
  </v-chip>
</template>

Можно изменить:

  • внешний вид чипов
  • формат текста
  • добавление иконок

Ограничение количества выбранных элементов

Ограничение реализуется через вычисляемые свойства или обработчики.

Пример:

<v-autocomplete
  v-model="selected"
  :items="items"
  multiple
  :disabled="selected.length >= 3"
/>

Более гибкий вариант — использование watch.

Очистка значения

Свойство clearable добавляет кнопку очистки.

<v-autocomplete
  v-model="value"
  :items="items"
  clearable
/>

При нажатии значение сбрасывается.

Работа с большим количеством данных

Для списков с тысячами элементов рекомендуется:

  • асинхронная загрузка
  • серверная фильтрация
  • виртуализация списка

Пример серверной фильтрации:

<v-autocomplete
  v-model="value"
  v-model:search="search"
  :items="items"
  :loading="loading"
  hide-no-data
/>

При изменении search отправляется API-запрос.

Основные свойства компонента

Свойство Назначение
items массив элементов
v-model выбранное значение
multiple множественный выбор
chips отображение выбранных элементов
clearable кнопка очистки
loading индикатор загрузки
item-title поле отображения
item-value поле значения
filter пользовательская функция поиска
v-model:search текст поиска

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

Компонент генерирует ряд событий.

Событие Назначение
update:modelValue изменение выбранного значения
update:search изменение текста поиска
focus получение фокуса
blur потеря фокуса

Пример:

<v-autocomplete
  :items="items"
  @update:modelValue="onChange"
/>

Стилизация компонента

Vuetify предоставляет несколько вариантов оформления.

Плотность

<v-autocomplete
  :items="items"
  density="compact"
/>

Варианты отображения

<v-autocomplete
  :items="items"
  variant="outlined"
/>

Доступные варианты:

  • outlined
  • filled
  • solo
  • underlined

Практический пример: поиск пользователя

Пример реального сценария — поиск пользователя по базе.

<v-autocomplete
  v-model="user"
  v-model:search="search"
  :items="users"
  item-title="name"
  item-value="id"
  :loading="loading"
  label="Поиск пользователя"
  hide-no-data
  clearable
/>
watch: {
  search(value) {
    if (!value) return

    this.loading = true

    fetch(`/api/users?q=${value}`)
      .then(r => r.json())
      .then(data => {
        this.users = data
      })
      .finally(() => {
        this.loading = false
      })
  }
}

Особенности:

  • поиск запускается при вводе текста
  • отображается индикатор загрузки
  • результаты приходят с сервера
  • пользователь выбирает найденный элемент

Когда использовать v-autocomplete

Компонент подходит для следующих задач:

  • выбор пользователя из базы
  • поиск города
  • выбор тега
  • выбор товара
  • поиск категории

Главное преимущество — быстрый поиск по большим спискам без необходимости прокрутки длинных меню.

Оглавление