В библиотеке MapLibre GL JS событийная модель построена вокруг объекта карты, который генерирует поток событий на разных этапах жизненного цикла, взаимодействия пользователя и обновления визуального состояния. Все события можно условно разделить на несколько крупных категорий: события жизненного цикла, события камеры, пользовательские интеракции, события данных и источников, а также технические события рендера и ошибок.
Такая структура позволяет отделять логику отображения, управление состоянием и обработку пользовательских действий, обеспечивая предсказуемость поведения карты.
Жизненный цикл карты охватывает этапы инициализации, загрузки стиля и готовности к работе.
loadСрабатывает после полной загрузки стиля, тайлов и ресурсов, необходимых для первого рендеринга.
Типичная особенность: событие вызывается один раз за жизненный цикл экземпляра карты, если не происходит полная переинициализация стиля.
style.loadВозникает после загрузки стиля, но до полной готовности всех тайлов и ресурсов.
Используется для:
idleСрабатывает, когда карта завершила все активные операции:
Фактически фиксирует состояние «покоя», при котором отсутствуют асинхронные операции.
Камера определяет геометрическое состояние отображения: центр, масштаб, наклон и вращение. Изменения камеры генерируют отдельный класс событий.
moveСрабатывает при любом изменении положения камеры:
Используется для синхронизации UI с текущим положением карты.
movestart и
moveendРазделяют процесс перемещения на начало и завершение.
movestart фиксирует момент начала изменения камерыmoveend фиксирует завершение всех переходовТакая пара событий позволяет реализовывать:
zoom /
zoomstart / zoomendОтслеживание масштабирования карты.
zoomstart — начало масштабированияzoom — процесс изменения масштабаzoomend — завершение измененияСобытия особенно важны при:
rotate /
rotatestart / rotateendОтвечают за изменение азимута карты.
Применяются в системах:
pitch /
pitchstart / pitchendИзменение угла наклона камеры.
Используется для:
Эта группа событий отражает действия пользователя с картой через мышь или сенсорный ввод.
click и
dblclickСобытия одиночного и двойного клика.
click используется для выбора объектов картыdblclick часто связан с увеличением масштабаСобытие содержит информацию о координатах, точке на экране и объектах под курсором.
mousedown,
mouseup, mousemoveНизкоуровневые события мыши.
Используются для:
mouseenter и
mouseleaveФиксируют вход и выход курсора в область карты.
Позволяют:
mouseover и
mouseoutРаботают аналогично DOM-событиям, но привязаны к слоям и объектам карты.
contextmenuСрабатывает при вызове контекстного меню (обычно правая кнопка мыши).
Используется для:
wheelОтвечает за прокрутку колеса мыши.
Основная область применения:
Для сенсорных устройств поддерживаются аналоги:
touchstarttouchmovetouchendЭти события критичны для мобильных картографических приложений, где жесты заменяют мышь.
Эта категория отражает состояние загрузки и обновления геоданных.
dataОбщее событие, сигнализирующее об изменении данных карты.
Срабатывает при:
dataloadingВозникает в момент начала загрузки данных.
Используется для:
sourcedataФокусируется на конкретных источниках данных.
Позволяет:
styledataСрабатывает при изменении или загрузке стиля.
Применяется в системах:
Рендеринг карты — непрерывный процесс, управляемый внутренним циклом отрисовки.
renderСрабатывает при каждом кадре отрисовки.
Используется для:
errorСобытие ошибок, возникающих при:
Содержит диагностическую информацию, необходимую для логирования и восстановления состояния.
Некоторые события отражают изменения не только камеры или данных, но и общего состояния карты.
resizeСрабатывает при изменении размеров контейнера карты.
Используется для:
removeВозникает при удалении экземпляра карты.
Позволяет:
Каждое событие в MapLibre GL JS передаёт объект, содержащий контекст выполнения.
Ключевые поля:
type — тип событияtarget — экземпляр картыoriginalEvent — нативное DOM-событие (если
применимо)point — координаты курсора в пикселяхlngLat — географические координатыfeatures — массив объектов карты под курсором (для
событий взаимодействия)Для событий камеры дополнительные поля могут включать:
bearingzoompitchСистема событий основана на паттерне наблюдателя.
Основные методы:
map.on(type, handler) — регистрация обработчикаmap.off(type, handler) — удаление обработчикаmap.once(type, handler) — одноразовое выполнениеПоведение обработчиков строго синхронизировано с внутренним циклом рендера, что исключает расхождения состояния при быстрых последовательных изменениях.
События генерируются в определённой последовательности, особенно при комплексных изменениях состояния.
Пример при зуме:
zoomstartmovezoommoveendzoomendidleТакая последовательность позволяет точно отслеживать этапы взаимодействия и строить предсказуемую реакцию интерфейса.
MapLibre GL JS использует WebGL-рендеринг, что накладывает особенности:
Это делает важным минимизацию логики внутри часто вызываемых событий,
таких как render или mousemove.
События могут быть привязаны к:
Фильтрация позволяет ограничивать область реагирования обработчиков, снижая нагрузку и повышая точность взаимодействия.
События карты часто используются как слой синхронизации между визуализацией и бизнес-логикой:
Эта модель позволяет строить реактивные геоинформационные интерфейсы, где карта выступает центральным источником событийного потока.