Breaking changes

Mapbox GL JS — библиотека для визуализации интерактивных карт в браузере с использованием WebGL. С каждым крупным обновлением возникают breaking changes — изменения, которые могут нарушить работу существующего кода при переходе на новую версию. Понимание этих изменений критично для поддержания стабильности проектов и грамотного планирования миграции.

Основные причины breaking changes

  1. Обновление API Разработчики иногда меняют сигнатуры методов, убирают устаревшие параметры или переименовывают функции для унификации. Например, методы управления источниками или слоями могут получить новые обязательные аргументы.

  2. Изменения формата данных Mapbox GL JS активно использует GeoJSON и собственные форматы для источников данных. Появление новых требований к структуре объектов, полей свойств или идентификаторов объектов может сломать отображение данных на карте.

  3. Обновления движка рендеринга Новые версии библиотеки используют оптимизации WebGL и изменяют поведение стилей и фильтров слоев. Старые настройки стиля могут перестать корректно работать, или визуальные эффекты могут измениться.

  4. Удаление устаревших возможностей Функции, помеченные как deprecated в предыдущих релизах, иногда полностью удаляются. Это касается как API работы с картой (map.addSource, map.addLayer), так и вспомогательных утилит (LngLatBounds.contains, Style.prototype.getLayer).

Примеры наиболее критичных изменений

1. Изменение методов работы со слоями

Ранее существовала возможность использовать строковые идентификаторы слоев для доступа к ним без проверки на существование. В новых версиях такие вызовы могут выбрасывать исключение:

map.getLayer('mylayer').setPaintProperty('fill-color', '#ff0000');

Если слой mylayer отсутствует, метод теперь возвращает undefined и может вызвать ошибку. Правильный подход — проверка существования слоя:

const layer = map.getLayer('mylayer');
if (layer) {
    layer.setPaintProperty('fill-color', '#ff0000');
}

2. Новые требования к источникам данных

В версии 2.x изменился формат определения источников типа geojson. Поле data теперь должно быть строго объектом GeoJSON или URL, а не обычной строкой с JSON:

map.addSource('points', {
    type: 'geojson',
    data: { type: 'FeatureCollection', features: [] } // корректно
});

Попытка передать строку с JSON приведет к ошибке: "data must be a valid GeoJSON object or URL".

3. Изменения фильтров и стилей

Фильтры filter теперь требуют строгого соответствия синтаксису Expression API. Старые массивные конструкции могут перестать работать:

// Старый синтаксис
filter: ['==', 'type', 'park']  

// Новый синтаксис
filter: ['==', ['get', 'type'], 'park']

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

4. Управление событиями

В новых версиях методы подписки на события on и off требуют корректного контекста. Использование устаревшего синтаксиса без привязки может привести к отсутствию вызова callback-функции:

function onClick(e) {
    console.log(e.features);
}
map.on('click', 'mylayer', onClick); // корректно
map.off('click', 'mylayer', onClick); // корректно

Стратегии работы с breaking changes

  • Тщательная проверка changelog Каждый крупный релиз сопровождается документированными изменениями. Разбор списка deprecated методов и новых требований к API помогает заранее адаптировать код.

  • Использование промежуточных версий Постепенное обновление, например, с 1.13 → 1.14 → 2.0, снижает риск внезапного выхода из строя функционала.

  • Тестирование критичных компонентов Карты с интерактивными слоями, источниками и фильтрами должны проходить юнит- и интеграционные тесты после обновления.

  • Обновление стилей и фильтров Перевод всех фильтров на Expression API и проверка корректности JSON-структур источников данных.

  • Создание абстракций Обёртки над слоями и источниками данных позволяют централизованно обрабатывать изменения API без переписывания всего проекта.

Важные нюансы

  • Версия библиотеки и её тип лицензии влияют на доступность новых функций. Mapbox GL JS 2.x требует ключа API, а 1.x можно использовать без ограничений.
  • Миграция на WebGL2 может вызвать проблемы с совместимостью старых браузеров. Необходимо проверять целевые платформы.
  • Некоторые breaking changes могут быть скрытыми: карта отображается, но поведение фильтров, анимаций или обработки событий изменяется.

Понимание и системная обработка breaking changes позволяют строить устойчивые приложения на Mapbox GL JS и минимизировать неожиданные сбои при обновлении библиотек.

Оглавление