В MapLibre GL JS взаимодействие с картой строится вокруг событийной модели. Почти любое изменение состояния карты, пользовательское действие или завершение внутреннего процесса рендеринга сопровождается генерацией событий, к которым подключаются обработчики.
События делятся на несколько крупных категорий: жизненный цикл карты, пользовательское взаимодействие, события слоёв и источников данных, а также низкоуровневые события рендеринга.
Базовый механизм подписки на события реализован через методы объекта карты:
on(type, listener) — добавление обработчикаoff(type, listener) — удаление обработчикаonce(type, listener) — одноразовое выполнение
обработчикаmap.on('load', () => {
console.log('Карта полностью загружена');
});Обработчики могут регистрироваться как на глобальные события карты, так и на события конкретных слоёв или источников.
События жизненного цикла отражают этапы инициализации и рендеринга карты.
loadСрабатывает после полной загрузки стиля, источников и ресурсов.
map.on('load', () => {
map.addSource('points', {
type: 'geojson',
data: '/data/points.geojson'
});
});idleСигнализирует, что карта завершила все рендер-операции и не выполняет активных обновлений.
Используется для синхронизации состояния интерфейса с завершением отрисовки.
renderСрабатывает при каждом цикле рендеринга. Частота высокая, требует осторожного использования.
map.on('render', () => {
console.log('Карта перерисовывается');
});removeВозникает при уничтожении экземпляра карты. Применяется для очистки ресурсов.
Карта генерирует события при изменении положения, масштаба и ориентации.
move, zoom,
rotate, pitchКаждое изменение параметров камеры вызывает соответствующее событие.
map.on('move', () => {
const center = map.getCenter();
console.log(center);
});moveendzoomendrotateendpitchendИспользуются для выполнения логики после завершения анимаций или пользовательских жестов.
map.on('zoomend', () => {
console.log('Зум завершён');
});MapLibre GL JS поддерживает события pointer-уровня:
clickdblclickmousedownmouseupmousemovemouseentermouseleavemouseovermouseoutmap.on('click', (e) => {
console.log(e.lngLat);
});Объект события содержит координаты, экранные координаты и данные о фичах под курсором.
Одним из ключевых механизмов является извлечение объектов слоя при взаимодействии.
queryRenderedFeaturesИспользуется для получения геообъектов под курсором или в области.
map.on('click', (e) => {
const features = map.queryRenderedFeatures(e.point, {
layers: ['cities-layer']
});
console.log(features);
});Типичный сценарий — обработка кликов по векторным слоям для отображения всплывающих окон или выделения объектов.
События могут привязываться к конкретным слоям, что позволяет ограничивать область обработки.
map.on('click', 'cities-layer', (e) => {
console.log('Клик по объекту слоя');
});Поддерживаются события:
clickmouseentermouseleavemousemoveМеханизм основан на hit-testing в пределах заданного слоя, что
снижает необходимость ручной фильтрации через
queryRenderedFeatures.
Источники данных генерируют события при обновлении или загрузке.
sourcedata — любые изменения данных источникаdata — глобальное событие обновления данныхdataloading — начало загрузкиdataabort — прерывание загрузкиmap.on('sourcedata', (e) => {
console.log(e.sourceId, e.isSourceLoaded);
});Эти события используются для синхронизации UI с состоянием данных и прогрузкой тайлов.
Изменения стиля карты также сопровождаются событиями:
styledatastyleimagemissingstyle.loadmap.on('styledata', () => {
console.log('Стиль изменён');
});styleimagemissing особенно важен при использовании
пользовательских иконок: событие сигнализирует об отсутствии изображения
в стиле.
Каждое событие содержит объект с информацией о контексте.
type — тип событияtarget — экземпляр картыlngLat — географические координатыpoint — экранные координатыfeatures — найденные геообъектыoriginalEvent — нативное DOM-событиеmap.on('click', (e) => {
console.log(e.type);
console.log(e.lngLat);
console.log(e.point);
});MapLibre GL JS использует систему приоритетов:
При совпадении обработчиков сначала выполняется наиболее специфичный уровень.
Метод once применяется для событий, которые должны
сработать единожды.
map.once('idle', () => {
console.log('Первое завершение рендера');
});Типичный сценарий — инициализация после первой полной отрисовки карты.
Удаление подписок критично при динамических интерфейсах и SPA-архитектурах.
function onClick(e) {
console.log(e.lngLat);
}
map.on('click', onClick);
map.off('click', onClick);Невычищенные обработчики приводят к утечкам памяти и дублированию логики.
События mousemove, render,
move генерируются с высокой частотой. Их обработка требует
оптимизации:
requestAnimationFramelet last;
map.on('mousemove', (e) => {
const now = Date.now();
if (now - last < 50) return;
last = now;
});Событийная модель часто используется для синхронизации UI:
map.on('mousemove', (e) => {
const features = map.queryRenderedFeatures(e.point);
updateSidebar(features);
});Типовой сценарий — привязка popups к кликам по объектам.
map.on('click', 'cities-layer', (e) => {
const coordinates = e.lngLat;
const description = e.features[0].properties.name;
new maplibregl.Popup()
.setLngLat(coordinates)
.setHTML(description)
.addTo(map);
});Сложные сценарии используют цепочки событий:
mousemove → подсветка объектаclick → фиксация выбораmouseleave → сброс состоянияzoomend → перерисовка интерфейсаТак формируется интерактивная модель поведения карты без прямого опроса состояния.
На мобильных устройствах события pointer объединяют мышь и сенсорный ввод. MapLibre GL JS абстрагирует различия через единый набор событий, сохраняя совместимость логики.
События рендеринга тесно связаны с WebGL-пайплайном:
События позволяют отслеживать эти процессы без доступа к внутренним механизмам WebGL.
Некоторые события сигнализируют о проблемах:
error — ошибки загрузки ресурсов или стиляstyleimagemissing — отсутствие изображенийdataabort — прерывание загрузки тайловmap.on('error', (e) => {
console.error(e.error);
});Эти события используются для построения устойчивых систем мониторинга и диагностики.