Deprecated функции

В экосистеме MapLibre GL JS устаревшие функции (deprecated) обозначают части публичного API, которые сохраняются для обратной совместимости, но не рекомендуются к использованию в новых проектах. Такие элементы постепенно теряют поддержку и могут быть удалены в будущих мажорных версиях.

Основная причина появления устаревших функций — эволюция архитектуры рендеринга карт, переход к более строгому соответствию спецификации Style Specification, а также оптимизация производительности WebGL-движка.

Ключевые признаки deprecated API:

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

Устаревшие подходы к инициализации карты

Ранние версии, унаследованные от Mapbox GL JS, использовали конфигурации, которые со временем были признаны избыточными или небезопасными.

accessToken как обязательный параметр

В классическом Mapbox GL JS доступ к API требовал установки токена:

mapboxgl.accessToken = 'TOKEN';

В MapLibre GL JS этот механизм считается устаревшим в контексте архитектуры, поскольку библиотека не привязана к конкретному облачному сервису. Использование токена сохраняется только как совместимость с существующим кодом.

Современный подход:

  • использование собственного tile server
  • явное указание style без зависимости от внешних API

Конструктор Map с избыточными опциями

Некоторые опции конструктора считались временными и постепенно исключались:

  • hash: true (в ряде реализаций заменён на более гибкие URL-хендлеры)
  • interactive: true (поведение теперь всегда управляется через event listeners)
  • устаревшие параметры управления canvas в ранних версиях

Современная архитектура предполагает, что интерактивность карты включена по умолчанию и управляется через события.

Устаревшие методы управления состоянием карты

setZoom / getZoom в синхронных цепочках

Хотя методы:

map.setZoom(10);
map.getZoom();

не удалены, устаревшим считается их использование в синхронных вычислительных цепочках, где раньше допускалось построение логики вида:

const zoom = map.setZoom(10).getZoom();

Современная модель разделяет операции изменения состояния и чтения через события moveend, zoomend.

jumpTo, easeTo и flyTo в старых паттернах анимации

Методы анимации карты:

  • jumpTo
  • easeTo
  • flyTo

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

Ранее применялись конструкции:

map.flyTo({ center: [0, 0], zoom: 5 });
map.flyTo({ zoom: 10 });

Проблема заключалась в накоплении анимационных переходов без отмены предыдущих.

Современный подход:

Использование stop() перед новой анимацией:

map.stop();
map.flyTo({ center: [0, 0], zoom: 5 });

Устаревшие обработчики событий

Старый стиль регистрации событий через on/off без namespace

Исторически использовались конструкции:

map.on('click', handler);
map.off('click', handler);

Устаревание связано не с самим API, а с отсутствием пространств имён событий и сложностью управления подписками.

В современных архитектурах рекомендуется:

  • использовать именованные функции
  • хранить ссылки на обработчики
  • группировать события логически

Устаревшие события загрузки стиля

Ранее активно использовались:

  • style.load
  • source.load

В современных версиях предпочтение отдаётся:

  • map.on('load')
  • map.isStyleLoaded()

Причина — унификация жизненного цикла карты.

Устаревшие методы работы со слоями

addLayer с неявной валидацией

Ранние версии позволяли добавлять слои без строгой проверки структуры:

map.addLayer({
  id: 'points',
  type: 'circle'
});

Отсутствие источника считалось допустимым в некоторых старых сборках, но позже стало deprecated-поведением.

Актуальная модель требует:

  • обязательного source
  • строгого соответствия style spec

removeLayer без проверки существования

Устаревший паттерн:

map.removeLayer('layer-id');

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

if (map.getLayer('layer-id')) {
  map.removeLayer('layer-id');
}

setLayoutProperty и setPaintProperty без актуализации стиля

Ранее изменения свойств слоёв не всегда синхронизировались с текущим стилем, что приводило к неочевидным багам.

Устаревшим считается использование этих методов без учёта жизненного цикла style reload.

Устаревшие источники данных (Sources API)

GeoJSON source с частыми полными перерисовками

Ранний подход:

map.getSource('points').setData(geojson);

при каждом изменении данных считался нормой.

Это поведение признано deprecated в высоконагруженных сценариях.

Причина:

  • полная переработка дерева данных
  • блокировка render loop
  • деградация FPS

Современная альтернатива:

  • использование diff-обновлений (через сторонние стратегии)
  • кластеризация
  • батчинг обновлений

image source через частую замену URL

Устаревший паттерн:

map.addSource('img', {
  type: 'image',
  url: 'frame1.png'
});

с последующей постоянной заменой url считался неэффективным.

Устаревшие методы работы с DOM и canvas

getCanvasContainer как основной способ управления UI

Ранее активно использовался:

map.getCanvasContainer();

для добавления пользовательских элементов.

Этот подход признан устаревшим для сложных интерфейсов, поскольку смешивает DOM-слой и WebGL-контекст.

Современная практика:

  • использование отдельных overlay-слоёв
  • интеграция с React/Vue поверх контейнера карты

remove() без очистки ресурсов

map.remove();

в старых версиях не всегда корректно освобождал WebGL контекст, что приводило к утечкам памяти.

Современные версии требуют гарантированного вызова очистки ресурсов перед удалением экземпляра карты.

Устаревшие утилитарные функции

mapboxgl.supported()

Функция:

mapboxgl.supported()

исторически использовалась для проверки поддержки WebGL.

В MapLibre GL JS она считается устаревшей в пользу:

  • WebGLRenderingContext проверки
  • feature detection через canvas.getContext('webgl')

Причина — необходимость независимости от глобального объекта mapboxgl.

requestAnimationFrame внутри API

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

Переход от deprecated API к современным паттернам

Основная стратегия миграции строится на трёх принципах:

Разделение состояния и представления

Ранее:

map.setCenter([0, 0]).setZoom(5);

Современный подход:

map.setCenter([0, 0]);
map.setZoom(5);

с последующей обработкой через события.

Контроль жизненного цикла карты

Использование событий:

  • load
  • idle
  • render
  • moveend

вместо синхронных проверок состояния.

Явное управление источниками и слоями

Ранее допускалась неявная структура данных, теперь требуется:

  • строгая типизация источников
  • явное определение слоя перед использованием
  • проверка существования объектов перед удалением

Практические сценарии миграции устаревшего кода

Обновление GeoJSON источника

Устаревший код:

setInterval(() => {
  map.getSource('points').setData(data);
}, 1000);

Проблема: постоянная полная перерисовка.

Современный подход:

  • агрегация изменений
  • обновление только при необходимости
  • использование debounce/throttle

Замена устаревших событий

Ранее:

map.on('style.load', initLayers);

Современный вариант:

map.on('load', initLayers);

или:

if (map.isStyleLoaded()) {
  initLayers();
}

Управление анимацией без конфликтов

Ранее:

map.flyTo({ center: A });
map.flyTo({ center: B });

Современный подход:

map.stop();
map.flyTo({ center: A });
setTimeout(() => {
  map.flyTo({ center: B });
}, 300);

или через очередь анимаций в пользовательской логике.

Проверка слоёв перед удалением

Ранее:

map.removeLayer('roads');

Современный вариант:

if (map.getLayer('roads')) {
  map.removeLayer('roads');
}

или через централизованный менеджер слоёв.

Архитектурные изменения, влияющие на устаревание API

Эволюция MapLibre GL JS привела к нескольким системным изменениям:

  • переход к строгой реализации style specification
  • усиление WebGL pipeline и отказ от синхронных паттернов
  • разделение UI и render logic
  • отказ от глобальных состояний
  • повышение предсказуемости событийной модели

Эти изменения напрямую формируют список deprecated функций и определяют их дальнейшую судьбу в API.

Оглавление