Система событий в Mapbox GL JS построена на расширенной модели событий, включающей взаимодействие с картой, слоями, источниками данных и DOM-подобными элементами внутри WebGL-контекста. Архитектура событий позволяет обрабатывать как низкоуровневые действия (движение мыши, прокрутка, касания), так и высокоуровневые события геообъектов (клик по слою, наведение на фичу, выбор объектов).
Событийная система базируется на паттерне подписки:
map.on(type, handler)map.off(type, handler)map.once(type, handler)События делятся на несколько категорий:
Каждое событие передаёт объект события, содержащий контекст: координаты, пиксельные позиции, список затронутых объектов, состояние камеры и другие параметры.
Основной набор событий мыши:
mousedownmouseupclickdblclickmousemovemouseovermouseoutcontextmenuЭти события работают на уровне canvas-контейнера карты. При этом координаты события доступны как:
event.point — пиксельные координатыevent.lngLat — географические координатыКлючевая особенность заключается в том, что события мыши могут быть связаны с географическими объектами через выборку фич на текущем слое.
Для мобильных устройств используются:
touchstarttouchendtouchcancelЖесты масштабирования и вращения не представлены как отдельные touch-события, а обрабатываются через абстракцию камеры.
Событие прокрутки:
wheelИспользуется для управления zoom камеры. Содержит данные о скорости прокрутки, направлении и инерции. Внутри Mapbox GL JS это событие часто перехватывается для управления плавностью масштабирования.
Камера карты — центральная абстракция отображения. Изменения её состояния генерируют следующие события:
movestartmovemoveendzoomstartzoomzoomendrotatestartrotaterotateendpitchstartpitchpitchendКаждая группа событий имеет структуру:
Эти события критичны для синхронизации UI: анимации, обновления данных, запросов к API.
Система рендера WebGL генерирует события состояния:
load — карта и стили загруженыrender — каждый кадр отрисовкиidle — отсутствие активных измененийerror — ошибка рендеринга или загрузки ресурсовОсобое значение имеет idle, сигнализирующий о завершении
всех асинхронных операций: загрузки тайлов, изображений, данных
источников.
Одной из ключевых возможностей является обработка событий на уровне слоёв:
map.on('click', 'layer-id', (e) => {
console.log(e.features);
});Поддерживаются события:
clickmouseentermouseleavemousemovemousedownmouseupПри этом система выполняет выборку объектов под курсором через:
queryRenderedFeaturesquerySourceFeaturesКаждое событие слоя содержит:
features — массив геообъектовlayer — идентификатор слояpoint — координаты пикселяlngLat — географические координатыДля реализации интерактивных эффектов наведения используется комбинация событий:
mouseentermouseleavemousemoveТипичный паттерн включает хранение текущего выделенного объекта и обновление визуального состояния слоя.
Оптимизированный подход предполагает использование:
setFeatureStategetFeatureStateПример логики:
hover: trueЭто позволяет избегать пересоздания источников данных и минимизировать перерендер.
Feature State используется для хранения интерактивных состояний без изменения исходных данных:
События взаимодействия часто комбинируются с этим механизмом:
mousemove → обновление hoverclick → установка selectedmouseleave → сброс состоянияВажное свойство — состояние привязано к source и
id, а не к визуальному объекту.
Система допускает управление распространением событий:
stopPropagation() — блокировка дальнейшей
обработкиЭто особенно важно при перекрывающихся слоях, где несколько геообъектов находятся под курсором.
Перетаскивание карты реализовано через последовательность:
mousedown / touchstartdragstartdragdragendDrag-события тесно связаны с камерой, так как изменяют
center, bearing, pitch.
Также используются:
Выбор объектов обычно реализуется через:
click по слоюqueryRenderedFeatures в точке кликаСобытие возвращает массив объектов, так как под курсором может находиться несколько фич.
Стратегии обработки:
Каждое интерактивное событие содержит два ключевых представления позиции:
point)lngLat)Преобразования между ними позволяют:
При интенсивных взаимодействиях (mousemove, touchmove) возникает высокая частота событий.
Основные оптимизации:
requestAnimationFramequeryRenderedFeaturesДополнительно применяется разделение логики:
Система генерирует error при:
Объект ошибки содержит:
Источники (sources) генерируют события:
sourcedatadatadataloadingОни позволяют отслеживать:
Сложные сценарии строятся через комбинации:
Пример логики взаимодействия:
mousemove определяет активный объектclick фиксирует выборzoomend пересчитывает кластерные группыidle запускает фоновые обновленияБольшинство пользовательских событий наследуются от базового класса событий карты и содержат:
typetargetoriginalEventlngLatpointfeaturesЭта структура обеспечивает унифицированный доступ к данным вне зависимости от источника события.
Слои в Mapbox GL JS являются основным уровнем, на котором строится интерактивность:
События слоя позволяют реализовать UI-поведение без отдельного DOM-слоя поверх карты.
При высокой интерактивности важна согласованность:
События выступают связующим слоем, синхронизируя эти уровни в реальном времени через единый event loop WebGL-контекста.