Первая интерактивная карта

Подключение и инициализация HERE Maps API в JavaScript начинается с загрузки SDK и создания базовой структуры карты, включающей платформу, слой отображения и объект карты, привязанный к DOM-контейнеру.

Для работы с картой требуется подключение JavaScript-бандла платформы HERE Technologies. Обычно используется CDN-скрипт, предоставляемый официальной платформой.

<link rel="stylesheet" type="text/css"
      href="https://js.api.here.com/v3/3.1/mapsjs-ui.css" />

<script src="https://js.api.here.com/v3/3.1/mapsjs-core.js"></script>
<script src="https://js.api.here.com/v3/3.1/mapsjs-service.js"></script>
<script src="https://js.api.here.com/v3/3.1/mapsjs-ui.js"></script>
<script src="https://js.api.here.com/v3/3.1/mapsjs-mapevents.js"></script>

Подключение разделено на несколько модулей:

  • mapsjs-core — базовые классы и инфраструктура
  • mapsjs-service — доступ к REST-сервисам платформы
  • mapsjs-ui — интерфейсные элементы управления
  • mapsjs-mapevents — обработка событий карты (drag, zoom, tap)

Создание платформенного объекта

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

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

Ключевые особенности:

  • apikey является обязательным параметром
  • объект Platform инкапсулирует доступ к тайлам, геокодированию и маршрутизации
  • через него создаются слои карты и сервисные клиенты

Получение слоёв карты

После создания платформы требуется получить стандартные слои отображения.

const defaultLayers = platform.createDefaultLayers();

Объект defaultLayers содержит набор предопределённых визуальных стилей:

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

Наиболее часто используется слой vector.normal.map.

Инициализация DOM-контейнера

Перед созданием карты необходим HTML-элемент, в котором будет отрисован canvas или SVG-контейнер.

<div id="mapContainer" style="width: 100%; height: 500px;"></div>

Размер контейнера критически важен: без заданной высоты карта не будет отображаться корректно.

Создание объекта карты

Основной объект карты создаётся через конструктор H.Map.

const map = new H.Map(
  document.getElementById('mapContainer'),
  defaultLayers.vector.normal.map,
  {
    center: { lat: 51.505, lng: -0.09 },
    zoom: 10,
    pixelRatio: window.devicePixelRatio || 1
  }
);

Параметры инициализации:

  • container — DOM-элемент
  • layer — выбранный слой отображения
  • center — начальные координаты центра карты
  • zoom — уровень масштабирования (обычно 1–20)
  • pixelRatio — оптимизация под HiDPI-экраны

Добавление поведения карты (pan, zoom, rotate)

Для интерактивности подключается поведенческий модуль.

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

Функциональные возможности:

  • перетаскивание карты (drag)
  • масштабирование колесом мыши
  • мультитач жесты на мобильных устройствах
  • инерционное движение

Без этого слоя карта остаётся статичной.

UI-компоненты управления

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

const ui = H.ui.UI.createDefault(map, defaultLayers);

Этот вызов автоматически добавляет:

  • кнопки zoom +/-
  • компас (ориентация)
  • переключатель слоёв (если доступен)
  • элементы масштабной линейки

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

Привязка карты к жизненному циклу окна

При изменении размеров окна карта должна пересчитывать viewport.

window.addEventListener('resize', () => {
  map.getViewPort().resize();
});

Это предотвращает:

  • искажение геометрии карты
  • неправильное позиционирование слоёв
  • рассинхронизацию canvas и контейнера

Управление центром и масштабом после инициализации

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

map.setCenter({ lat: 52.52, lng: 13.405 });
map.setZoom(12);

Также поддерживаются плавные переходы:

map.setZoom(14, true);

или комбинированное изменение вида:

map.setViewBounds(bounds);

Работа с системой координат

HERE Maps использует WGS84 (широта/долгота) как базовую систему координат.

Основные правила:

  • lat — широта (−90 до 90)
  • lng — долгота (−180 до 180)
  • порядок всегда { lat, lng }

Для внутренних вычислений SDK преобразует координаты в проекцию Web Mercator.

Инициализация с учётом производительности

При создании карты учитываются параметры рендеринга:

const map = new H.Map(container, layer, {
  center: { lat: 48.8566, lng: 2.3522 },
  zoom: 11,
  pixelRatio: Math.min(window.devicePixelRatio, 2)
});

Оптимизации:

  • ограничение pixelRatio снижает нагрузку на GPU
  • использование векторных тайлов повышает качество масштабирования
  • отключение лишних UI-компонентов ускоряет загрузку

Обработка готовности платформы

Некоторые операции требуют ожидания инициализации сервиса.

platform.getService().then(service => {
  console.log('Service ready');
});

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

Интеграция нескольких слоёв отображения

Карты поддерживают переключение между стилями:

const satelliteLayer = platform.createDefaultLayers().satellite.map;
map.setBaseLayer(satelliteLayer);

Основные типы слоёв:

  • стандартная карта (vector/raster)
  • спутниковые снимки
  • гибридные режимы
  • пользовательские тайлы

Контроль ошибок и проверка ключа API

При неверном ключе или отсутствии доступа карта не инициализируется корректно.

Типичные симптомы:

  • пустой контейнер
  • ошибки загрузки тайлов
  • отсутствие сетевых запросов к сервису

Рекомендуется отслеживать события:

map.addEventListener('mapviewchange', function () {
  console.log('View changed');
});

Минимальный полный сценарий инициализации

Объединённая структура инициализации включает все ключевые шаги:

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

const defaultLayers = platform.createDefaultLayers();

const map = new H.Map(
  document.getElementById('mapContainer'),
  defaultLayers.vector.normal.map,
  {
    center: { lat: 51.505, lng: -0.09 },
    zoom: 10,
    pixelRatio: window.devicePixelRatio || 1
  }
);

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

const ui = H.ui.UI.createDefault(map, defaultLayers);

window.addEventListener('resize', () => {
  map.getViewPort().resize();
});

Архитектурная модель инициализации

Инициализация карты строится по трёхуровневой модели:

  1. Platform layer — доступ к API и сервисам
  2. Rendering layer — создание карты и управление слоями
  3. Interaction layer — события, UI, поведение пользователя

Такая структура обеспечивает независимость компонентов и позволяет расширять систему без изменения базовой логики отображения.

Оглавление