Событие highlightItem

Событие highlightItem в Choices.js срабатывает в момент, когда пользователь или программная логика изменяет состояние подсветки элемента в списке доступных опций. Подсветка (highlight) отличается от выбора тем, что элемент не добавляется в выбранные значения, а лишь становится активным в выпадающем интерфейсе, что особенно важно при навигации с клавиатуры и при кастомной отрисовке списка.

Внутренне Choices.js использует систему управления состояниями списка, где каждый элемент проходит через этапы отображения: фильтрация, рендеринг, навигация и взаимодействие. Событие highlightItem относится к стадии навигационного взаимодействия и фиксирует текущий активный элемент списка.

highlightItem вызывается в следующих сценариях:

  • перемещение по списку с помощью клавиш ↑ и ↓
  • наведение курсора мыши на элемент выпадающего списка
  • программное изменение активного элемента через API Choices.js
  • пересчет списка после фильтрации, когда фокус автоматически переносится на первый подходящий элемент

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

Структура объекта события

Событие передает объект, содержащий контекст текущего состояния списка. Типичная структура выглядит следующим образом:

{
  id: 12,
  value: "option_value",
  label: "Option Label",
  group: null,
  active: true,
  highlighted: true,
  customProperties: {},
  score: 0.87
}

Ключевые поля:

  • id — внутренний идентификатор элемента
  • value — значение, которое будет использовано при выборе
  • label — отображаемый текст
  • active — флаг активности элемента в DOM-структуре
  • highlighted — подтверждение состояния подсветки
  • customProperties — пользовательские метаданные, привязанные к опции
  • score — релевантность при поисковой фильтрации

Подключение обработчика

Choices.js предоставляет систему событий, основанную на on-подписках. Подключение обработчика для highlightItem осуществляется через экземпляр компонента.

const choices = new Choices('#select', {
  shouldSort: false
});

choices.passedElement.element.addEventListener(
  'highlightItem',
  (event) => {
    console.log('Highlighted:', event.detail);
  }
);

В большинстве случаев данные события передаются в event.detail, где содержится объект элемента.

Поведение при навигации с клавиатуры

При использовании клавиатуры highlightItem становится центральным механизмом управления визуальной подсветкой. При каждом нажатии клавиши:

  • вычисляется новый индекс активного элемента
  • снимается подсветка с предыдущего элемента
  • назначается новый highlighted-элемент
  • генерируется событие highlightItem

Важно учитывать, что событие может срабатывать очень часто при удержании клавиши, что влияет на производительность обработчиков.

Влияние фильтрации на событие

При включенной поисковой строке Choices.js (searchEnabled: true) событие highlightItem тесно связано с фильтрацией списка.

После ввода текста:

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

Это поведение важно учитывать при реализации кастомной логики подсветки, так как событие может возникать синтетически.

В экосистеме Choices.js существует несколько близких событий:

  • change — фиксирует изменение выбранных значений
  • addItem — добавление элемента в выбранные
  • removeItem — удаление выбранного элемента
  • search — изменение поискового запроса
  • highlightItem — изменение активного (но не выбранного) элемента

Ключевое отличие highlightItem заключается в отсутствии модификации состояния выбранных данных. Это исключительно UI-событие навигации.

Использование для кастомного UI

При построении собственного интерфейса поверх Choices.js highlightItem используется для синхронизации состояния интерфейса:

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

Пример интеграции:

choices.passedElement.element.addEventListener('highlightItem', (event) => {
  const item = event.detail;

  updatePreviewPanel({
    title: item.label,
    meta: item.customProperties
  });
});

Частые особенности поведения

При работе с событием наблюдаются характерные нюансы:

  • повторное срабатывание при ререндере списка
  • отсутствие события при кликах вне списка
  • сброс highlight при закрытии dropdown
  • автоматическое назначение первого элемента после поиска

Эти особенности связаны с внутренней моделью виртуального списка, используемой Choices.js.

Производительность обработчиков

Так как highlightItem может вызываться с высокой частотой, обработчики должны быть легковесными. Типичные проблемы:

  • выполнение DOM-операций внутри обработчика без оптимизации
  • тяжелые вычисления на каждое перемещение
  • синхронные запросы внутри события

Практика обработки:

let lastId = null;

choices.passedElement.element.addEventListener('highlightItem', (event) => {
  const item = event.detail;

  if (item.id === lastId) return;
  lastId = item.id;

  requestAnimationFrame(() => {
    renderSidebar(item);
  });
});

Сценарии применения в сложных интерфейсах

В комплексных формах highlightItem часто используется как триггер вспомогательной логики:

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

Такое использование превращает событие из простого UI-индикатора в механизм синхронизации интерфейсных модулей.

Поведение при программном управлении

Choices.js позволяет изменять highlight программно через внутренние методы. При этом:

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

Это обеспечивает единообразие логики независимо от источника изменения состояния.

Оглавление