Deprecated API

Mapbox GL JS активно развивается, и с каждым новым релизом появляются изменения в API. Некоторые функции устаревают и помечаются как deprecated, что означает их постепенное удаление в будущих версиях. Использование устаревших методов может привести к несовместимости, поэтому важно знать, какие элементы API больше не рекомендуется применять, и как правильно их заменять.

Методы управления картой

map.fitBounds(bounds, options) Ранее использовался для масштабирования и центрирования карты по заданной области. Этот метод остаётся рабочим, но в новых версиях рекомендуется использовать более точные и гибкие методы:

  • Замена: использование map.jumpTo(), map.easeTo() или map.flyTo() с указанием bounds через объект CameraOptions.
  • Преимущество: современные методы позволяют задавать анимацию, длительность перехода, кривую интерполяции и ограничивать поворот камеры.

Пример устаревшего вызова:

map.fitBounds([[lng1, lat1], [lng2, lat2]], { padding: 20 });

Современный аналог:

map.fitBounds([[lng1, lat1], [lng2, lat2]], {
  padding: {top: 20, bottom: 20, left: 20, right: 20},
  duration: 1000
});

Объекты источников данных

Ранее API активно использовало методы addSource и removeSource без строгой типизации. Сейчас рекомендуются более безопасные практики:

  • Deprecated: добавление источников без указания type или с устаревшими типами данных.
  • Рекомендация: явно указывать тип источника (geojson, vector, raster, image) и все обязательные поля.
  • Пример устаревшего способа:
map.addSource('myData', {
  data: myGeoJson
});
  • Современный способ:
map.addSource('myData', {
  type: 'geojson',
  data: myGeoJson,
  cluster: true,
  clusterRadius: 50
});

Это позволяет избежать ошибок при взаимодействии слоёв и упрощает работу с кластеризацией и фильтрацией данных.

Управление слоями

С устаревшими методами для слоёв связаны следующие ключевые моменты:

  1. setLayoutProperty(layerId, name, value) Ранее использовался для изменения свойств отображения слоёв. Хотя метод работает, рекомендуется использовать обновлённый подход через setLayerPaintProperty и setLayerLayoutProperty с точным указанием типа свойства.

  2. setFilter(layerId, filter) Фильтры слоёв теперь рекомендуется задавать в виде массива условий с поддержкой всех новых операторов, вместо строковых выражений. Это повышает читаемость и совместимость с будущими версиями.

  3. Удаление слоёв с помощью removeLayer(layerId) Сам метод не устарел, но важно сначала удалять все зависимости, такие как связанные источники или обработчики событий, чтобы избежать ошибок.

События карты

map.on('mousemove', callback) и другие устаревшие обработчики событий остаются рабочими, однако новые версии Mapbox GL JS предлагают следующие улучшения:

  • Использование map.on('move', callback) вместо прямого отслеживания координат через mousemove.
  • Новая структура событий позволяет получать расширенные данные о состоянии камеры, зуме, наклоне и повороте карты.
  • Deprecated также касается методов вроде map.off(), если они вызываются без проверки наличия события, что могло приводить к непредвиденным ошибкам.

Геометрические функции

Некоторые функции работы с геометрией и координатами больше не поддерживаются:

  • LngLat.convert() считается устаревшим. Вместо него рекомендуется создавать объекты через конструктор:
const point = new mapboxgl.LngLat(lng, lat);
  • Методы вроде point.toArray() остаются рабочими, но следует использовать их совместно с современными структурами данных для интеграции с GeoJSON.

Стили и источники изображений

  • Свойства типа sprite и glyphs в объекте стиля не должны изменяться динамически через устаревшие методы.
  • Для добавления растровых изображений и иконок следует использовать map.addImage(name, image, options) с корректными параметрами sdf и pixelRatio.
  • Устаревший способ загрузки изображений через прямое добавление в style.layers может вызвать ошибки рендеринга в новых версиях.

Практические рекомендации

  • Проверять changelog каждой версии Mapbox GL JS. Многие методы помечаются как deprecated за несколько релизов до полного удаления.
  • Использовать современные альтернативы для всех операций с картой: переходы камеры, управление слоями, источниками и событиями.
  • Встроенные типы объектов (LngLat, LngLatBounds, CameraOptions) применять строго по документации, избегая устаревших конструкторов и методов.
  • Регулярно тестировать проект на совместимость с последней версией библиотеки, чтобы выявлять deprecated-функции заранее.

Хотя Mapbox GL JS поддерживает многие устаревшие методы для обратной совместимости, переход на актуальные подходы обеспечивает стабильность, предсказуемость и масштабируемость веб-карт.

Оглавление