Базовая HTML-структура приложения

Стартовая точка любого веб-приложения с картографическим функционалом на базе HERE Maps API — корректно сформированная HTML-структура. Именно она определяет, где будет отображаться карта, как подключаются внешние библиотеки и каким образом инициализируется логика приложения.

Минимальный HTML-документ должен включать три ключевых элемента:

  • подключение мета-данных документа;
  • контейнер для отображения карты;
  • подключение JavaScript SDK и пользовательского кода.

Базовый каркас страницы

Основой служит стандартная HTML-разметка, в которую интегрируется карта:

<!DOCTYPE html>
<html lang="ru">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>HERE Map Application</title>

    <style>
        html, body {
            height: 100%;
            margin: 0;
            padding: 0;
        }

        #map {
            width: 100%;
            height: 100%;
        }
    </style>
</head>

<body>
    <div id="map"></div>

    <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>

    <script src="app.js"></script>
</body>
</html>

Контейнер карты как обязательный элемент DOM

Элемент <div id="map"></div> является точкой монтирования карты. Вся визуализация происходит внутри него.

Ключевые требования к контейнеру:

  • наличие уникального id, используемого в JavaScript;
  • явная заданная высота (без высоты карта не отображается);
  • отсутствие внутренних отступов, если требуется полноэкранный режим.

Частая ошибка — отсутствие высоты у родительских элементов. В этом случае карта не появляется, несмотря на корректную инициализацию API.

CSS-структура и управление размером карты

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

html, body {
    height: 100%;
    margin: 0;
}

#map {
    width: 100%;
    height: 100%;
}

В более сложных интерфейсах контейнер часто размещается внутри layout-сетки:

.layout {
    display: flex;
    height: 100vh;
}

.sidebar {
    width: 300px;
}

.map-container {
    flex: 1;
}
<div class="layout">
    <div class="sidebar"></div>
    <div id="map" class="map-container"></div>
</div>

Подключение библиотек HERE Maps

Архитектура HERE Maps API основана на модульной загрузке скриптов. Каждый модуль отвечает за отдельный функциональный слой:

  • mapsjs-core.js — базовая логика и объекты карты;
  • mapsjs-service.js — доступ к REST-сервисам (геокодинг, маршруты);
  • mapsjs-ui.js — элементы управления интерфейсом;
  • mapsjs-mapevents.js — обработка событий мыши и сенсоров.

Порядок подключения критически важен: сначала ядро, затем сервисы и UI.

Инициализация платформы и карты

После загрузки библиотек создаётся объект платформы:

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.5200, lng: 13.4050 },
        zoom: 10,
        pixelRatio: window.devicePixelRatio || 1
    }
);

Подключение взаимодействия с картой

Для обработки пользовательских событий подключается модуль событий:

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

Добавляется UI:

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

Эти два компонента обеспечивают:

  • масштабирование колесом мыши;
  • перетаскивание карты;
  • отображение контролов интерфейса.

Центровка и управление состоянием карты

Карта управляется через методы объекта map:

map.setCenter({ lat: 48.8566, lng: 2.3522 });
map.setZoom(12);

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

Адаптация под размер окна

При изменении размеров окна необходимо уведомлять карту:

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

Без этого карта может некорректно пересчитывать координаты и отображение тайлов.

Структурирование проекта

Типичная структура проекта с использованием HERE Maps API:

project/
│
├── index.html
├── styles.css
├── app.js
└── assets/

Вынесение логики в отдельный файл app.js обеспечивает:

  • разделение ответственности;
  • упрощение масштабирования;
  • повторное использование компонентов.

Контейнеризация логики и инициализация приложения

В app.js обычно выделяется функция инициализации:

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

    const layers = platform.createDefaultLayers();

    const map = new H.Map(
        document.getElementById('map'),
        layers.vector.normal.map,
        {
            center: { lat: 40.7128, lng: -74.0060 },
            zoom: 11
        }
    );

    const events = new H.mapevents.MapEvents(map);
    new H.mapevents.Behavior(events);

    H.ui.UI.createDefault(map, layers);
}

window.onl oad = initMap;

Особенности загрузки SDK

Загрузка скриптов через CDN предполагает:

  • зависимость от сети;
  • необходимость корректного порядка подключения;
  • возможность кэширования браузером.

Для производственных проектов часто применяются:

  • локальное хранение SDK;
  • сборка через bundler (Webpack, Vite);
  • ленивое подключение модулей.

Базовые принципы устойчивой HTML-структуры

Корректная архитектура HTML-приложения с картой строится на нескольких принципах:

  • карта всегда имеет явный контейнер;
  • размеры контейнера определены через CSS, а не через JS;
  • SDK загружается до пользовательского кода;
  • логика инициализации отделена от разметки;
  • события окна синхронизируются с viewport карты.
Оглавление