Migration guides

Основные принципы миграции

Mapbox GL JS активно развивается, и новые версии библиотеки иногда вводят изменения в API, стили и методы работы с картой. При переходе с более старых версий (например, v0.x–v1.x) на современные (v2.x–v3.x) важно учитывать несколько ключевых аспектов:

  1. Лицензирование – начиная с версии 2.x, Mapbox GL JS требует токен с действующей подпиской. Это значит, что любые старые проекты на версии 1.x, использующие бесплатный ключ, могут столкнуться с ограничениями.

  2. ESM-модули – новые версии Mapbox GL JS распространяются как ECMAScript модули. Импорт библиотеки через <script> с CDN остаётся возможным, но рекомендуется переход на современный синтаксис:

    import mapboxgl from 'mapbox-gl';
mapboxgl.accessToken = 'YOUR_ACCESS_TOKEN';

  3. Совместимость CSS – стиль контейнера карты и управление слоями по-прежнему требуют подключения CSS-файла библиотеки:

    <link href='https://api.mapbox.com/mapbox-gl-js/v3.0.0/mapbox-gl.css' rel='stylesheet' />

Инициализация карты

В новых версиях структура инициализации карты сохраняется, но добавлены новые параметры конфигурации:

const map = new mapboxgl.Map({
    container: 'map', // id HTML-элемента
    style: 'mapbox://styles/mapbox/streets-v12', // новый стиль
    center: [37.618423, 55.751244], // долгота, широта
    zoom: 10, // уровень масштабирования
    projection: 'mercator', // поддержка новых проекций
    antialias: true // сглаживание рендеринга
});

Ключевые изменения:

  • style теперь поддерживает версии стилей v12+. Старые стили v8–v11 могут требовать обновления.
  • Параметр projection позволяет задавать проекции, отличные от стандартной Меркаторской.
  • antialias улучшает визуальное качество рендеринга 3D-объектов.

Работа со слоями и источниками данных

В Mapbox GL JS 2.x–3.x появились расширенные возможности работы с источниками данных и слоями:

  1. Источники данных:

    map.addSource('points', {
    type: 'geojson',
    data: 'data/points.geojson',
    cluster: true,
    clusterRadius: 50
});
    • cluster и clusterRadius позволяют группировать объекты на карте автоматически.
    • Поддержка источников vector, raster, geojson и image осталась без изменений.

  2. Слои:

    map.addLayer({
    id: 'point-layer',
    type: 'circle',
    source: 'points',
    paint: {
        'circle-radius': 6,
        'circle-color': '#FF5722'
    }
});
    • В новых версиях для symbol-слоев улучшена работа с иконками и текстом.
    • Для fill-extrusion добавлена поддержка height-transition, что позволяет анимировать высоту 3D-объектов.

Обработка событий

События карты остались совместимыми с прошлым API, но появились новые типы событий для современных слоёв и проекций:

map.on('click', 'point-layer', (e) => {
    const features = map.queryRenderedFeatures(e.point, { layers: ['point-layer'] });
    console.log(features);
});
  • mouseenter и mouseleave теперь более плавно работают с динамическими слоями.
  • Добавлены события moveend и zoomend с расширенными параметрами, отражающими текущую проекцию.

Управление камерами и анимациями

Новые версии делают анимацию камеры более гибкой:

map.flyTo({
    center: [37.618423, 55.751244],
    zoom: 14,
    bearing: 45,
    pitch: 60,
    speed: 1.2, // скорость анимации
    curve: 1.5 // кривизна траектории
});
  • Появились параметры speed и curve, которые позволяют точно управлять визуальной траекторией перемещения.
  • Методы easeTo и jumpTo поддерживаются с теми же аргументами, что и раньше, но теперь интегрируются с системой плавных переходов между проекциями.

Обновление слоёв и стилей на лету

Mapbox GL JS 3.x позволяет динамически изменять свойства слоёв без полной перезагрузки карты:

map.setPaintProperty('point-layer', 'circle-color', '#4CAF50');
map.setLayoutProperty('point-layer', 'visibility', 'none');
  • setPaintProperty и setLayoutProperty обеспечивают мгновенное обновление визуальных характеристик.
  • Метод removeLayer теперь автоматически удаляет связанные с ним источники данных, если они не используются другими слоями.

Использование новых функций стилей

  • Light & Shadow: новые возможности для sky-layer и освещения 3D-объектов.
  • Data-driven styling: улучшена поддержка функций выражений (expressions) для динамического изменения свойств слоёв на основе данных.
  • Layer ordering: оптимизировано управление порядком слоёв через moveLayer, что снижает необходимость полной перезагрузки карты при сложных стилях.

Особенности миграции с Mapbox GL JS v1.x

  1. Удалены устаревшие события – style.load, tile.load и data.load изменили сигнатуру обратного вызова.
  2. Deprecated методы – getStyle().layers остаётся, но прямое редактирование массива слоёв больше не рекомендуется.
  3. Работа с иконками – старый подход с addImage без опций sdf и pixelRatio может привести к неправильному отображению на ретина-дисплеях.

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

  • Всегда проверять соответствие токена лицензии версии библиотеки.
  • Обновлять стили карт с v10+ для корректной работы с современными функциями.
  • Переписать обработчики событий с учётом новых возможностей анимации и проекций.
  • Использовать expressions для динамического стилизования, избегая ручного изменения каждого свойства слоя.

Итоговые заметки по миграции

Миграция с Mapbox GL JS v1.x на v2.x–v3.x требует внимательного пересмотра работы с токенами, источниками данных, слоями и событиями. Использование современных функций анимации, проекций и выражений повышает гибкость и производительность карт, а соблюдение новых рекомендаций позволяет создавать интерактивные приложения с расширенными возможностями визуализации.

Оглавление