Подключение библиотеки через CDN

Подключение HERE Maps API через CDN является самым быстрым способом начать работу с картографическими сервисами HERE в веб-приложениях. Такой подход не требует установки пакетов через npm, настройки сборщиков проектов или конфигурации модулей. Все необходимые библиотеки загружаются непосредственно с серверов HERE при открытии страницы.

CDN-подключение особенно удобно для:

  • учебных проектов;
  • прототипирования интерфейсов;
  • небольших веб-приложений;
  • тестирования функциональности API;
  • быстрого изучения возможностей платформы HERE.

Основная идея заключается в подключении готовых JavaScript-файлов и таблиц стилей через теги <script> и <link>.

Регистрация и получение API Key

Перед подключением библиотеки необходимо получить ключ доступа.

Последовательность действий:

  1. Создать учетную запись на платформе HERE.
  2. Создать новый проект.
  3. Сгенерировать API Key.
  4. Сохранить полученный ключ для дальнейшего использования в приложении.

API Key используется для авторизации запросов к сервисам платформы и является обязательным параметром при инициализации карты.

Пример ключа:

const apiKey = "YOUR_API_KEY";

Вместо строки YOUR_API_KEY необходимо использовать реальный ключ, выданный платформой HERE.

Подключение необходимых файлов

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

Подключение CSS

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

Этот файл отвечает за стили пользовательского интерфейса карты:

  • кнопки масштабирования;
  • панели управления;
  • элементы навигации;
  • информационные окна.

Подключение основного ядра API

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

Модуль содержит базовую инфраструктуру библиотеки:

  • работу с объектами карты;
  • управление событиями;
  • взаимодействие с платформой HERE.

Подключение сервиса карт

<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-mapevents.js"></script>

Позволяет работать с:

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

Подключение пользовательского интерфейса

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

Добавляет готовые элементы управления:

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

Полный набор подключений

Чаще всего используется следующий комплект:

<!DOCTYPE html>
<html lang="ru">
<head>
    <meta charset="UTF-8">

    <link
        rel="stylesheet"
        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-mapevents.js"></script>
    <script src="https://js.api.here.com/v3/3.1/mapsjs-ui.js"></script>

    <title>HERE Maps</title>
</head>
<body>

</body>
</html>

После загрузки этих файлов библиотека становится доступной через глобальный объект H.

Создание контейнера для карты

Карта отображается внутри HTML-элемента.

Пример:

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

Для корректного отображения необходимо задать размеры.

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

Если размеры не указаны, карта не будет видна, поскольку элемент получит нулевую высоту.

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

После подключения библиотеки создается объект платформы.

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

Объект Platform выступает точкой входа ко всем сервисам HERE.

Через него можно получать:

  • картографические слои;
  • сервис маршрутизации;
  • сервис поиска;
  • сервис геокодирования.

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

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

const defaultLayers = platform.createDefaultLayers();

Метод возвращает объект с различными вариантами отображения карт.

Примеры слоев:

defaultLayers.vector.normal.map
defaultLayers.vector.normal.traffic
defaultLayers.raster.normal.map

Наиболее часто используется:

defaultLayers.vector.normal.map

Это современная векторная карта с поддержкой масштабирования и высокой производительности.

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

Следующий шаг — создание экземпляра карты.

const map = new H.Map(
    document.getElementById("map"),
    defaultLayers.vector.normal.map,
    {
        zoom: 10,
        center: {
            lat: 55.7558,
            lng: 37.6176
        }
    }
);

Параметры конструктора:

Параметр Описание
Контейнер HTML-элемент для отображения
Слой карты Источник картографических данных
Настройки Центр карты и масштаб

Добавление взаимодействия с картой

Без подключения обработчиков карта остается статичной.

Для активации взаимодействия используется следующий код:

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

После этого становятся доступны:

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

Подключение пользовательского интерфейса

Для отображения стандартных элементов управления выполняется инициализация UI.

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

После выполнения кода на карте автоматически появятся:

  • кнопки изменения масштаба;
  • элементы управления отображением;
  • дополнительные компоненты интерфейса.

Полный минимальный пример

Ниже представлен полноценный пример страницы с HERE Maps API, подключенной через CDN.

<!DOCTYPE html>
<html lang="ru">
<head>
<meta charset="UTF-8">

<link
    rel="stylesheet"
    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-mapevents.js"></script>
<script src="https://js.api.here.com/v3/3.1/mapsjs-ui.js"></script>

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

<body>

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

<script>

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,
    {
        zoom: 12,
        center: {
            lat: 55.7558,
            lng: 37.6176
        }
    }
);

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

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

</script>

</body>
</html>

После открытия страницы будет отображена интерактивная карта с центром в Москве и стандартными элементами управления.

Структура подключаемых модулей

Каждый подключаемый файл отвечает за отдельную часть функциональности.

Файл Назначение
mapsjs-core.js Базовое ядро библиотеки
mapsjs-service.js Сервисы HERE Platform
mapsjs-mapevents.js Обработка событий
mapsjs-ui.js Интерфейс пользователя
mapsjs-ui.css Стили UI-компонентов

Такое разделение позволяет подключать только необходимые модули и уменьшать объем загружаемых данных.

Например, если пользовательский интерфейс не нужен, можно отказаться от:

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

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

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

После подключения CDN-файлов глобальный объект H должен существовать в браузере.

Проверка:

console.log(H);

Или:

if (typeof H !== "undefined") {
    console.log("HERE Maps загружен");
}

При успешной загрузке в консоли появится объект со всеми пространствами имен библиотеки.

Типичные ошибки при CDN-подключении

Неверный API Key

Симптомы:

  • карта не отображается;
  • появляются ошибки авторизации;
  • запросы получают ответ 401.

Пример ошибки:

Unauthorized

Необходимо проверить правильность ключа и его статус в панели управления HERE.

Отсутствует высота контейнера

Ошибка:

<div id="map"></div>
#map {
    width: 100%;
}

В этом случае карта не отображается.

Правильно:

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

Неправильный порядок подключения

Некоторые модули зависят от ядра библиотеки.

Неверно:

<script src="mapsjs-ui.js"></script>
<script src="mapsjs-core.js"></script>

Верно:

<script src="mapsjs-core.js"></script>
<script src="mapsjs-service.js"></script>
<script src="mapsjs-mapevents.js"></script>
<script src="mapsjs-ui.js"></script>

Выполнение кода до загрузки DOM

Ошибка возникает, если контейнер карты еще не существует.

Неверно:

const map = new H.Map(
    document.getElementById("map"),
    layer
);

при расположении скрипта выше элемента:

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

Правильные варианты:

<script>
...
</script>
</body>

или

window.addEventListener("DOMContentLoaded", () => {
    // код инициализации
});

Преимущества использования CDN

Простота подключения

Достаточно добавить несколько тегов <script> и <link>.

Быстрый старт

Карта может быть запущена в течение нескольких минут после получения API Key.

Отсутствие сборки проекта

Не требуется настройка Webpack, Vite, Parcel или других инструментов.

Автоматическая доставка файлов

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

Удобство обучения

CDN-подключение позволяет сосредоточиться на изучении возможностей HERE Maps API без дополнительной инфраструктурной настройки.

Когда CDN-подключение подходит лучше всего

Наиболее эффективным данный способ является в следующих сценариях:

  • изучение HERE Maps API;
  • создание учебных примеров;
  • разработка демонстрационных проектов;
  • тестирование новых возможностей платформы;
  • разработка небольших сайтов без сложной сборки JavaScript.

Для крупных приложений с модульной архитектурой чаще применяется установка пакетов через npm и интеграция библиотеки в систему сборки проекта, однако CDN-подключение остается базовым и наиболее наглядным способом начала работы с HERE Maps API в JavaScript.

Оглавление