Переход с других картографических библиотек

Переход между картографическими библиотеками требует переосмысления базовой архитектуры отображения карт, поскольку различия затрагивают не только API, но и саму модель данных, подход к слоям, обработку событий и взаимодействие с геосервисами. В экосистеме веб-картографии часто сравниваются HERE Maps API, Google Maps Platform, Leaflet и Mapbox GL JS, и именно различия между ними определяют стратегию миграции.

Основное отличие заключается в уровне абстракции:

  • Leaflet использует модель слоёв (tile layers) и ориентирован на простую интеграцию растровых тайлов.
  • Google Maps Platform предоставляет высокоуровневый сервис с закрытой инфраструктурой и минимальной настройкой рендеринга.
  • Mapbox GL JS и HERE Maps API опираются на векторный рендеринг с GPU-ускорением и декларативной стилизацией.

HERE Maps API реализует гибридный подход: сочетание векторных тайлов, WebGL-рендеринга и сервисного слоя (геокодирование, маршрутизация, изохроны). Это делает миграцию с Leaflet более радикальной, а с Mapbox GL JS — более концептуальной, чем технической.

Базовая модель карты и контейнер

В Leaflet карта создаётся через объект L.map, а слои добавляются отдельно:

const map = L.map('map').setView([52.5, 13.4], 10);

L.tileLayer('https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png').addTo(map);

В HERE Maps API используется объектная модель платформы:

const platform = new H.service.Platform({
  apikey: 'YOUR_API_KEY'
});

const defaultLayers = platform.createDefaultLayers();

const map = new H.Map(
  document.getElementById('map'),
  defaultLayers.vector.normal.map,
  {
    center: { lat: 52.5, lng: 13.4 },
    zoom: 10,
    pixelRatio: window.devicePixelRatio
  }
);

const beh * avior = new H.mapevents.Behavior(new H.mapevents.MapEvents(map));

Ключевое отличие заключается в обязательном слое поведения (H.mapevents.Behavior), который заменяет привычную систему взаимодействий Leaflet и частично перекрывает event-handling Google Maps.

Слои, тайлы и стилизация

Leaflet оперирует тайловыми URL-шаблонами и CSS-подобной логикой отображения. Mapbox GL JS и HERE используют векторные стили.

В HERE стили задаются через предустановленные слои:

defaultLayers.vector.normal.map
defaultLayers.raster.satellite.map

В отличие от Mapbox GL JS, где стиль описывается JSON-конфигурацией, HERE предоставляет готовые стилевые наборы, ограничивая, но упрощая контроль:

map.setBaseLayer(defaultLayers.vector.hybrid.map);

При миграции с Mapbox GL JS важно учитывать отсутствие прямого аналога полной кастомизации слоя через style specification. Вместо этого применяется комбинация базовых слоёв и тематических параметров платформы.

Маркеры и объекты на карте

В Leaflet маркеры создаются напрямую:

L.marker([52.5, 13.4]).addTo(map);

В HERE Maps API используется объект H.map.Marker:

const marker = new H.map.Marker({ lat: 52.5, lng: 13.4 });
map.addObject(marker);

Особенность заключается в том, что все объекты наследуются от базового H.map.Object, что позволяет унифицировать работу с геометриями:

  • Marker
  • Polyline
  • Polygon
  • Circle

В Google Maps Platform аналогичная модель реализована через классы google.maps.Marker, но отличается системой событий и жизненного цикла объектов.

Геокодирование и обратное геокодирование

В Leaflet геокодирование не встроено и подключается через сторонние сервисы.

В Google Maps используется:

geocoder.geocode({ address: 'Berlin' })

В HERE применяется сервисный слой:

const geocoder = platform.getSearchService();

geocoder.geocode(
  { q: 'Berlin' },
  result => console.log(result),
  error => console.error(error)
);

Миграция с Google Maps требует замены структуры запросов: address → q, изменение формата ответа и обработчиков результатов.

Маршрутизация и сервисные запросы

В HERE маршрутизация отделена от UI-карты:

const router = platform.getRoutingService(null, 8);

router.calculateRoute(
  {
    transportMode: 'car',
    origin: '52.5,13.4',
    destination: '52.51,13.45',
    return: 'polyline'
  },
  result => console.log(result),
  error => console.error(error)
);

В Google Maps:

directionsService.route({
  origin: ...,
  destination: ...,
  travelMode: 'DRIVING'
});

Ключевая разница заключается в том, что HERE возвращает более низкоуровневую структуру маршрута, требующую ручного декодирования полилиний и явного управления отображением.

Миграция с Google Maps Platform

При переходе с Google Maps Platform основная трансформация касается:

  • замены классов google.maps.* на H.*
  • изменения системы событий (addListener → map.addEventListener)
  • переработки геосервисов

Пример трансформации маркера:

// Google Maps
const marker = new google.maps.Marker({
  position: { lat: 52.5, lng: 13.4 },
  map
});

// HERE Maps
const marker = new H.map.Marker({ lat: 52.5, lng: 13.4 });
map.addObject(marker);

Существенное отличие заключается в отсутствии привязки объекта к карте при создании — добавление выполняется отдельно.

Миграция с Leaflet

При переходе с Leaflet изменяется фундаментальная модель слоёв.

Leaflet:

  • тайловая сетка
  • независимые плагины
  • DOM-ориентированная отрисовка

HERE:

  • WebGL-рендеринг
  • объектная модель сцены
  • централизованная платформа сервисов

Пример замены слоя:

// Leaflet
L.tileLayer(url).addTo(map);

// HERE
map.setBaseLayer(defaultLayers.vector.normal.map);

Основная сложность миграции заключается в отказе от URL-шаблонов тайлов и переходе к предопределённым слоям платформы.

Миграция с Mapbox GL JS

При переходе с Mapbox GL JS сохраняется концепция векторного рендера, но меняется модель стилизации и API управления сценой.

Mapbox:

map.setStyle('mapbox://styles/mapbox/streets-v11');

HERE:

map.setBaseLayer(defaultLayers.vector.normal.map);

Mapbox предоставляет полноценный стиль JSON, тогда как HERE использует преднастроенные стилевые конфигурации, что ограничивает перенос кастомных визуальных решений.

Полилинии в Mapbox:

map.addSource(...)
map.addLayer(...)

В HERE:

const line = new H.map.Polyline(points);
map.addObject(line);

Таким образом, переход требует отказа от декларативного style-spec в пользу объектной графовой модели.

Обработка событий и взаимодействие

Leaflet использует:

map.on('click', handler);

HERE:

map.addEventListener('tap', event => {
  console.log(event.target);
});

Различие заключается в унификации событий через MapEvents, который вводит дополнительный слой абстракции между DOM и картой.

Типичные ошибки при переносе логики

  • использование Leaflet-тайлов вместо базовых слоёв HERE
  • попытка применить Google Maps-style binding объектов к карте при создании
  • ожидание JSON-style конфигурации Mapbox GL
  • неправильная обработка координат (HERE чаще использует {lat, lng}, а не массивы)
  • игнорирование обязательного слоя поведения H.mapevents.Behavior
  • попытка использовать DOM-события вместо событий карты

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

Оглавление