Работа с MapLibre GL JS строится вокруг строго управляемого жизненного цикла объекта карты. Этот цикл охватывает инициализацию, загрузку стиля, добавление источников и слоёв, отрисовку, обновления состояния, а также корректное уничтожение экземпляра карты. Понимание этих этапов критично для стабильной работы приложений, предотвращения утечек памяти и корректного управления ресурсами WebGL.
Жизненный цикл начинается с создания экземпляра карты:
На этом этапе объект карты существует, но визуальное содержимое ещё не готово. Карта не считается полностью инициализированной до завершения загрузки стиля.
Ключевые моменты инициализации:
center, zoom,
bearing, pitchСледующий этап — загрузка стиля. Именно стиль определяет визуальное представление карты: источники данных, слои, фильтры, изображения, шрифты.
События жизненного цикла, связанные со стилем:
style.load — стиль загружен и применёнload — карта полностью готова к работеerror — ошибка загрузки ресурсовstyledata — изменение структуры стиляsourcedata — загрузка данных источниковКарта считается функционально готовой после события
load. До этого момента любые операции с слоями и
источниками могут быть нестабильными или откладываться.
После загрузки карта переходит в фазу непрерывного рендеринга. Этот цикл основан на WebGL и работает по принципу запросов кадра (requestAnimationFrame).
Основные триггеры рендера:
События:
render — каждый кадр отрисовкиidle — отсутствие изменений, карта «успокоилась»move — изменение положения картыzoom — изменение масштабаrotate — вращениеСостояние idle особенно важно для оптимизации: оно
сигнализирует, что карта завершила все активные обновления и может быть
использована для тяжёлых операций (например, снимков или аналитики).
Источники данных (sources) являются динамической частью жизненного цикла карты. Они могут добавляться, обновляться и удаляться в любой момент после загрузки стиля.
Этапы работы источника:
addSourceСобытия:
sourcedata — обновление данных источникаdata — завершение загрузки данныхdataloading — начало загрузки данныхОсобое внимание требуется при динамических источниках:
Слои (layers) — визуальная часть карты, зависящая от источников. Их жизненный цикл тесно связан со стилем.
Основные операции:
addLayer)moveLayer)setPaintProperty,
setLayoutProperty)removeLayer)Слой проходит несколько внутренних стадий:
Ошибки жизненного цикла слоёв часто возникают при:
Метод setStyle запускает один из самых сложных сценариев
жизненного цикла.
При смене стиля происходит:
События:
styledata — промежуточные изменения структурыstyle.load — завершение загрузки нового стиляВажно учитывать:
Ресурсы карты также имеют собственный жизненный цикл:
Событие:
styleimagemissing — отсутствие изображения в стилеПри этом:
Жизненный цикл карты тесно связан с пользовательским вводом.
Основные события:
mousedown, mousemove,
mouseuptouchstart, touchmove,
touchendclick, dblclickwheel (zoom)Эти события влияют на:
При высокой частоте взаимодействия важно учитывать:
В SPA-приложениях жизненный цикл карты должен быть синхронизирован с жизненным циклом компонента.
Типичный сценарий:
mountunmountКритические моменты:
removeПравильное завершение жизненного цикла включает:
map.remove()Метод remove завершает жизненный цикл карты.
Происходит:
Без корректного вызова удаления возможны:
Экземпляр карты не предназначен для повторной инициализации после удаления. Вместо этого используется создание нового объекта.
Попытки повторного использования приводят к:
Во время активной работы карта постоянно изменяет внутреннее состояние:
Это состояние неявно синхронизируется между:
Любое вмешательство должно учитывать асинхронность обновлений и
возможные race conditions между событиями render,
data и idle.