Если вариантов немного и поиск не нужен — возьмите CdsSelect. Если пользователь может вводить значения вне списка — CdsCombobox.
Анатомия
Первая схема — каркас компонента: лейбл, описание, поле и блок сообщений. Вторая — устройство самого поля: зона выбранного значения, кнопка очистки и индикатор меню; внутренние и внешние зоны иконок — те же, что у CdsTextInput.
Вариации
Автокомплит повторяет вариации CdsSelect — группировку, «Выбрать все», настройку списка и меню. Ниже — то, что добавляет поиск.
Элементы списка
Список задаёт проп items — массив строк или объектов с тем же интерфейсом, что у CdsList. Начните вводить — список отфильтруется по заголовкам элементов, совпавшие фрагменты подсветятся.
Поиск по нескольким полям
По умолчанию фильтр сравнивает запрос с заголовком элемента. Проп filter-keys расширяет область поиска: title — заголовок, raw.* — путь к полю исходного объекта. Своя логика сравнения задаётся функцией custom-filter, а no-filter отключает встроенную фильтрацию целиком — например, когда результаты уже отфильтрованы сервером.
Автовыбор первого элемента
Свойство auto-select-first подсвечивает первый подходящий элемент — Enter или Tab выбирают его без стрелок и клика. Значение exact подсвечивает элемент, только когда запрос совпал с заголовком полностью.
Множественный выбор и чипы
Свойство multiple разрешает выбрать несколько значений, chips показывает их тегами CdsTag, а closable-chips добавляет крестик — значение снимается прямо в поле. clear-on-select очищает поисковый запрос после каждого выбора, hide-selected убирает уже выбранные элементы из списка.
Слоты
Слоты меню и поля — те же, что у CdsSelect и CdsTextInput; примеры item, selection, chip и слотов меню смотрите на странице селекта — в автокомплите они работают так же.
| Имя слота | Описание |
|---|---|
item | Элемент списка целиком; получает item, index и props |
selection | Выбранное значение в поле |
chip | Чип выбранного значения (при chips) |
prepend-item / append-item | Контент до и после списка |
no-data | Контент меню при пустом результате поиска |
subheader / divider | Подзаголовок и разделитель группы |
menu-header / menu-footer | Шапка и подвал меню; получают search и filteredItems |
Слот no-data в автокомплите видят чаще, чем в селекте: запрос легко опечатать. Свяжите запрос через v-model:search и предложите выход — например, добавить введённое значение в справочник.
Рекомендации
Сценарии использования
Поиск с сервера
Когда справочник слишком большой для загрузки целиком, ищите на сервере: v-model:search отдаёт запрос, ответ кладётся в items, а no-filter отключает повторную фильтрацию на клиенте. loading показывает, что идёт запрос, а слот no-data меняет надпись пустого меню по состоянию: подсказка до ввода, «Ищем…» во время запроса, «Ничего не найдено» после пустого ответа — меню никогда не остаётся пустым.
Выбор получателей
Сочетание multiple, chips, closable-chips и clear-on-select собирает получателей тегами и сразу готово к следующему вводу. filter-keys ищет и по имени, и по почте, hide-selected убирает уже добавленных из списка, а слот item показывает аватар и адрес — так проще не ошибиться в однофамильцах.
Отправка формы
Автокомплит участвует в валидации CdsForm наравне с текстовыми полями: rules не пропустит форму без выбранного города. Помните, что значением остаётся только выбранный элемент — набранный текст без выбора в модель не попадает.
Большой справочник
Меню рендерит элементы через виртуальную прокрутку, поэтому список на десятки тысяч позиций не тормозит ни при открытии, ни при фильтрации. auto-select-first ускоряет ввод: набрали номер — нажали Enter.
API
Пропсы
| Имя | Тип | По умолчанию | Описание |
|---|---|---|---|
active | boolean | undefined | — | Активное состояние поля |
activeColor | string | undefined | — | Цвет компонента, когда он находится в активном состоянии |
appendIcon | IconValue | undefined | — | Иконка в слоте append после контента |
appendInnerIcon | IconValue | undefined | — | Иконка во внутреннем слоте append после содержимого поля |
autocomplete | string | undefined | 'off' | Помогает влиять на предложения браузера. Значение «suppress» изменяет атрибут name полей, а значение «off» полагается на то, что браузер по собственной инициативе перестанет предлагать значения. Любое другое значение передается встроенной функции автозаполнения для соответствующего элемента. |
autofocus | boolean | undefined | — | Включает автофокус |
autoSelectFirst | boolean | "exact" | undefined | — | Подсвечивает первый подходящий элемент списка при вводе; Enter или Tab выбирают его.
Значение exact подсвечивает только при полном совпадении поискового запроса с заголовком элемента. |
baseColor | string | undefined | — | Цвет неактивного компонента |
bgColor | string | undefined | — | Цвет фона компонента |
centerAffix | boolean | undefined | — | Выровнять по вертикали элементы appendInner, prependInner, clearIcon и label по центру. |
chips | boolean | undefined | — | Отображает выбранные значения в виде удаляемых чипов (CdsTag). |
clearable | boolean | undefined | — | Отображать кнопку очистки значения |
clearIcon | IconValue | undefined | 'remove' | Иконка кнопки очистки |
clearOnSelect | boolean | undefined | — | Очищает поисковый запрос после выбора элемента (актуально для multiple). |
closableChips | boolean | undefined | — | Добавляет чипам кнопку удаления (актуально вместе с chips). |
closeText | string | undefined | '$cds.close' | Текст для скринридеров, описывающий действие закрытия меню. |
color | string | undefined | — | Цвет компонента |
counter | string | number | boolean | undefined | — | Счетчик символов. Принимает булево значение, число или строку |
counterValue | number | ((value: any) => number) | undefined | — | Пользовательское значение счетчика. Может быть числом или функцией вычисления от текущего значения |
customFilter | FilterFunction | undefined | — | Своя функция фильтрации значений. Получает значение, поисковый запрос и элемент, возвращает совпадение или -1 |
customKeyFilter | FilterKeyFunctions | undefined | — | Отдельные функции фильтрации для конкретных ключей элемента — объект вида { ключ: функция } |
description | string | undefined | — | Описание компонента, отображаемое под меткой |
disabled | boolean | null | undefined | null | Заблокированное состояние |
eager | boolean | undefined | — | Рендерит контент меню заранее, не дожидаясь первого открытия. |
ellipsis | boolean | undefined | — | В режиме multiple удерживает выбранные значения в одну строку с многоточием |
error | boolean | undefined | — | Состояние ошибки |
errorMessages | string | readonly string[] | null | undefined | [] | Отображает компонент в состояние ошибки и передает пользовательские сообщения об ошибках.
Будет объединяться с любыми проверками, заданными в свойстве rules.
Это поле не запускает валидацию. |
filterKeys | FilterKeys | undefined | ['title'] | Ключи элемента, по которым идёт поиск. По умолчанию фильтрация идёт по заголовку элемента |
filterMode | FilterMode | undefined | 'intersection' | Как объединяются результаты customKeyFilter и общей фильтрации: пересечением, объединением или заменой |
focused | boolean | undefined | — | Управляет состоянием фокуса компонента. Когда true, компонент считается сфокусированным и может применять соответствующие стили или поведение. |
hideDetails | boolean | "auto" | undefined | — | Скрытие блока с деталями (сообщениями и подсказками). При значении 'auto' блок скрывается, если нет сообщений |
hideMessages | boolean | undefined | — | Скрыть сообщения под полем ввода |
hideNoData | boolean | undefined | — | Скрывает меню и плейсхолдер «нет данных», когда список элементов пуст. |
hideSelected | boolean | undefined | — | Скрывает уже выбранные элементы из списка меню. |
hint | string | undefined | — | Текст подсказки, отображаемый под полем ввода |
iconColor | string | boolean | undefined | — | Цвет иконки. Принимает булево значение или строку с цветом |
id | string | undefined | — | Уникальный идентификатор компонента |
isSelectAll | string | boolean | undefined | false | Добавляет первым элементом списка пункт «Выбрать все» (только для multiple).
true использует надпись по умолчанию $cds.selectAll, строка задаёт собственную надпись. |
itemChildren | SelectItemKey | false | Свойство объекта, содержащее дочерние элементы, либо функция для их получения |
itemColor | string | undefined | — | Цвет выбранных элементов в списке меню. По умолчанию используется color. |
itemProps | SelectItemKey | 'props' | Свойство объекта, содержащее пропсы для элемента, либо функция для их получения |
items | any[] | undefined | [] | Массив элементов для отображения |
itemTitle | SelectItemKey | 'title' | Свойство объекта, используемое как заголовок элемента, либо функция для его получения |
itemType | SelectItemKey | 'type' | Свойство объекта, определяющее тип элемента (item, divider, subheader), либо функция для его получения |
itemValue | SelectItemKey | 'value' | Свойство объекта, используемое как значение элемента, либо функция для его получения |
label | string | undefined | — | Текст метки (label) компонента |
listProps | CdsListProps | undefined | — | Пропсы, прокидываемые во внутренний компонент CdsList. |
loading | string | boolean | undefined | — | Индикатор загрузки для компонента |
maxErrors | string | number | undefined | 1 | Максимальное число отображаемых ошибок при валидации |
maxWidth | string | number | undefined | — | Максимальная ширина компонента |
menu | boolean | undefined | — | Управляет состоянием открытия выпадающего меню (v-model:menu). |
menuHeight | string | number | undefined | 178 | Максимальная высота выпадающего меню. |
menuIcon | IconValue | undefined | 'chevron-down' | Иконка-индикатор раскрытия меню. |
menuProps | CdsMenuProps | undefined | — | Пропсы, прокидываемые во внутренний компонент CdsMenu. |
messages | string | readonly string[] | undefined | [] | Сообщения для отображения под полем ввода |
minWidth | string | number | undefined | — | Минимальная ширина компонента |
modelModifiers | Record<string, boolean> | undefined | — | Модификаторы v-model, переданные Vue для обработки значения поля |
modelValue | any | null | Значение компонента в v-model. Если компонент поддерживает свойство multiple, по умолчанию используется пустой массив. |
multiple | boolean | undefined | — | Разрешает выбор нескольких значений. Выбранные элементы отображаются чипами или списком. |
name | string | undefined | — | Имя поля ввода |
noDataText | string | undefined | '$cds.noDataText' | Текст, отображаемый в меню, когда список элементов пуст. |
noFilter | boolean | undefined | — | Отключает встроенную фильтрацию — список показывается как есть, поиск обрабатывается снаружи |
openOnClear | boolean | undefined | — | Открывает меню после очистки значения. |
openText | string | undefined | '$cds.open' | Текст для скринридеров, описывающий действие открытия меню. |
persistentClearable | boolean | undefined | — | Всегда отображать кнопку очистки, а не только при наведении или фокусе |
persistentCounter | boolean | undefined | — | Всегда отображать счетчик, а не только при взаимодействии с полем |
persistentHint | boolean | undefined | — | Всегда отображать подсказку, а не только при фокусе |
persistentPlaceholder | boolean | undefined | — | Всегда отображать placeholder, а не скрывать его при взаимодействии с полем |
placeholder | string | undefined | — | Текст-заполнитель, отображаемый в пустом поле |
prefix | string | undefined | — | Текстовый префикс, отображаемый перед значением поля |
prependIcon | IconValue | undefined | — | Иконка в слоте prepend перед контентом |
prependInnerIcon | IconValue | undefined | — | Иконка во внутреннем слоте prepend перед содержимым поля |
readonly | boolean | null | undefined | null | Только для чтения |
returnObject | boolean | undefined | — | Возвращать в значении модели объект вместо массива |
reverse | boolean | undefined | — | Обратный порядок расположения элементов внутри поля |
role | string | undefined | 'combobox' | ARIA-роль для нативного элемента ввода |
rules | readonly ValidationRule[] | undefined | [] | Принимает массив, состоящий из элементов различных типов: функций, логических значений и строк. Функции принимают входное значение в качестве аргумента и должны возвращать либо true / false, либо строку, содержащую сообщение об ошибке. Поле ввода перейдет в состояние ошибки, если функция возвращает значение false (или любое значение в массиве содержит false) либо является строкой. |
search | string | undefined | — | Текущее значение поискового запроса для фильтрации элементов (v-model:search). |
size | number | "xs" | "sm" | "md" | "lg" | "xl" | undefined | 'md' | Размер компонента |
suffix | string | undefined | — | Текстовый суффикс, отображаемый после значения поля |
textColor | string | undefined | — | Цвет текста компонента |
theme | string | undefined | — | Тема компонента |
transition | string | boolean | (TransitionProps & { component?: Component | undefined; }) | { component: Component; } | null | undefined | { component: CdsModalTransition } | Анимация перехода |
type | string | undefined | 'text' | Тип нативного поля ввода |
validateOn | ValidateOn | undefined | — | Изменяет тип события, при котором запускается валидация |
valueComparator | ValueComparator | undefined | — | Функция сравнения значений элементов для определения выбранного состояния |
width | string | number | undefined | — | Ширина компонента |
События
| Имя | Тип | Описание |
|---|---|---|
update:focused | [focused: boolean] | Изменение состояния фокуса компонента (v-model:focused). |
update:menu | [value: boolean] | Изменение состояния открытия выпадающего меню (v-model:menu). |
update:modelValue | [value: any] | Изменение выбранного значения (v-model). |
update:search | [value: string] | Изменение поискового запроса (v-model:search). |
update:selectedAll | [value: boolean] | Изменение состояния «выбраны все» (только для multiple + isSelectAll). |
Слоты
| Имя | Тип | Описание |
|---|---|---|
append | CdsInputSlot | Добавляет элемент после поля ввода |
append-inner | CdsInputDefaultSlot | Слот, добавляемый в конце инпута ввода |
append-item | any | Контент после списка элементов в меню. |
chip | { item: any; internalItem: ListItem<any>; index: number; props: Record<string, unknown>; } | Кастомный рендеринг чипа выбранного значения (актуально вместе с chips). |
clear | CdsInputDefaultSlot & { props: Record<string, any>; } | Слот для пользовательского иконки очистки (отображается, когда свойство clearable имеет значение «true»). |
description | { description: string | undefined; props: Record<string, any>; } | Слот по умолчанию для компонента CdsDescription |
details | CdsInputSlot | Слот для ввода пользовательских данных, позволяющее настраивать отображение сообщений |
divider | { props: Record<string, unknown>; index: number; } | Кастомный рендеринг разделителя в списке меню. |
item | { item: any; internalItem: ListItem<any>; index: number; props: Record<string, unknown>; } | Кастомный рендеринг элемента списка в меню. |
label | { label: string | undefined; props: Record<string, any>; } | Слот по умолчанию для компонента CdsLabel |
loader | LoaderSlotProps | Слот для пользовательского загрузчика (отображается, если свойство loading имеет значение true). |
menu-footer | { search: Ref<string | undefined, string | undefined>; filteredItems: ListItem<any>[]; } | Контент подвала меню. Получает текущий поисковый запрос и отфильтрованные элементы. |
menu-header | { search: Ref<string | undefined, string | undefined>; filteredItems: ListItem<any>[]; } | Контент шапки меню. Получает текущий поисковый запрос и отфильтрованные элементы. |
message | CdsMessageSlot | Слот для настройки содержания сообщения |
messages | CdsInputSlot | Слот для ввода пользовательских данных, позволяющее настраивать отображение сообщений |
no-data | any | Контент, отображаемый в меню, когда список элементов пуст. |
prepend | CdsInputSlot | Добавляет элемент до поля ввода |
prepend-inner | CdsInputDefaultSlot | Слот, добавляемый в начало инпута ввода |
prepend-item | any | Контент перед списком элементов в меню. |
selection | { item: any; internalItem: ListItem<any>; index: number; } | Кастомный рендеринг выбранного значения в поле ввода. |
subheader | { props: Record<string, unknown>; index: number; } | Кастомный рендеринг подзаголовка группы в списке меню. |
Exposed
| Имя | Тип | Описание |
|---|---|---|
controlRef | HTMLElement | undefined | Ref-ссылка на контролл поля ввода |
fieldIconColor | string | undefined | Цвет иконки |
filteredItems | ListItem<any>[] | Элементы, отфильтрованные по текущему поисковому запросу. |
isDirty | boolean | Является ли поле ввода "грязным" |
isDisabled | boolean | Является ли поле ввода заблокированным |
isFocused | boolean | Находится ли компонент в фокусе. |
isPure | boolean | Не изменялся ли поисковый запрос с момента последнего выбора. Является ли поле ввода "чистым" |
isReadonly | boolean | Является ли поле ввода только для чтения |
isValid | boolean | null | Является ли поле ввода валидным |
isValidating | boolean | Является ли поле ввода в процессе валидации |
reset | () => Promise<void> | Функция сброса поля ввода в исходное состояние |
resetValidation | () => Promise<void> | Функция сброса валидации поля ввода |
selectAll | () => void | Переключить выбор всех доступных элементов (только для multiple + isSelectAll). |
validate | (silent?: boolean) => Promise<string[]> | Функция валидации поля ввода |