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

Подключение Mapbox GL JS через CDN (Content Delivery Network) является самым быстрым способом начала работы с библиотекой. В этом случае все необходимые файлы загружаются с удалённых серверов, а разработчику не требуется устанавливать пакет через npm, настраивать сборщики проектов или выполнять дополнительные шаги подготовки.

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

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

После подключения браузер получает доступ ко всем классам, методам и объектам библиотеки через глобальное пространство имён mapboxgl.

Что необходимо для работы Mapbox GL JS

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

  1. JavaScript-файл библиотеки.
  2. CSS-файл со стилями элементов карты.

Без подключения CSS карта может отображаться некорректно: исчезнут элементы управления, нарушится позиционирование интерфейса, возникнут проблемы с отображением всплывающих окон и навигационных кнопок.

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

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

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

    <style>
        body {
            margin: 0;
        }

        #map {
            width: 100vw;
            height: 100vh;
        }
    </style>
</head>
<body>

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

<script src="https://api.mapbox.com/mapbox-gl-js/v3.0.0/mapbox-gl.js"></script>

</body>
</html>

После загрузки страницы объект mapboxgl становится доступным для использования в JavaScript.

Структура подключения

Подключение таблицы стилей

В секции <head> размещается ссылка на CSS-файл:

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

Этот файл отвечает за:

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

Подключение JavaScript-библиотеки

Перед закрывающим тегом </body> обычно подключается основной скрипт:

<script src="https://api.mapbox.com/mapbox-gl-js/v3.0.0/mapbox-gl.js"></script>

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

mapboxgl.Map
mapboxgl.Marker
mapboxgl.Popup
mapboxgl.NavigationControl
mapboxgl.GeolocateControl

и другие компоненты библиотеки.

Подготовка контейнера карты

Mapbox GL JS отображает карту внутри HTML-элемента.

Наиболее распространённый вариант:

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

Затем контейнеру задаются размеры:

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

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

Частая ошибка начинающих разработчиков:

#map {
    width: 100%;
}

Без свойства height карта не отображается.

Получение Access Token

Mapbox использует систему авторизации через Access Token.

Токен представляет собой строку вида:

pk.eyJ1IjoidXNlciIsImEiOiJjbG...

Он выдаётся в личном кабинете Mapbox и используется для доступа к:

  • стилям карт;
  • тайлам;
  • геокодированию;
  • дополнительным сервисам платформы.

Перед созданием карты токен указывается следующим образом:

mapboxgl.accessToken = 'ВАШ_ACCESS_TOKEN';

Обычно эта строка располагается перед созданием объекта карты.

Создание первой карты

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

mapboxgl.accessToken = 'ВАШ_ACCESS_TOKEN';

const map = new mapboxgl.Map({
    container: 'map',
    style: 'mapbox://styles/mapbox/streets-v12',
    center: [37.6176, 55.7558],
    zoom: 10
});

В результате в контейнере появится интерактивная карта.

Разбор параметров конструктора

Основной класс библиотеки:

new mapboxgl.Map(options)

Объект настроек может содержать множество параметров.

container

Определяет контейнер для отображения карты.

По идентификатору:

container: 'map'

Или по ссылке на DOM-элемент:

container: document.getElementById('map')

style

Указывает стиль карты.

Пример:

style: 'mapbox://styles/mapbox/streets-v12'

Популярные стили:

mapbox://styles/mapbox/streets-v12
mapbox://styles/mapbox/outdoors-v12
mapbox://styles/mapbox/light-v11
mapbox://styles/mapbox/dark-v11
mapbox://styles/mapbox/satellite-v9
mapbox://styles/mapbox/satellite-streets-v12

center

Определяет центр карты.

Формат:

center: [долгота, широта]

Пример:

center: [30.3141, 59.9386]

Для Санкт-Петербурга.

zoom

Уровень масштабирования.

zoom: 5

Типичные значения:

Масштаб Назначение
1–3 Континенты
4–6 Страны
7–10 Регионы
11–14 Города
15–18 Улицы
19–22 Детальный просмотр

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

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

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

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

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

</head>
<body>

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

<script src="https://api.mapbox.com/mapbox-gl-js/v3.0.0/mapbox-gl.js"></script>

<script>

mapboxgl.accessToken = 'ВАШ_ACCESS_TOKEN';

const map = new mapboxgl.Map({
    container: 'map',
    style: 'mapbox://styles/mapbox/streets-v12',
    center: [37.6176, 55.7558],
    zoom: 10
});

</script>

</body>
</html>

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

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

CDN позволяет использовать определённую версию Mapbox GL JS.

Пример:

<script src="https://api.mapbox.com/mapbox-gl-js/v3.2.0/mapbox-gl.js"></script>

И соответствующий CSS:

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

Использование фиксированной версии обеспечивает:

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

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

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

console.log(mapboxgl);

В консоли браузера должен появиться объект библиотеки.

Также можно проверить наличие конструктора карты:

console.log(mapboxgl.Map);

Если выводится функция-конструктор, подключение выполнено успешно.

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

Отсутствует Access Token

Ошибка:

An API access token is required

Причина:

mapboxgl.accessToken = '';

или строка вовсе отсутствует.

Решение — указать действительный токен Mapbox.

Не подключён CSS-файл

Подключён только Jav * aScript:

<script src="...mapbox-gl.js"></script>

В результате карта может выглядеть некорректно.

Необходимо добавить:

<link
    href="...mapbox-gl.css"
    rel="stylesheet"
/>

Контейнер имеет нулевую высоту

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

#map {
    width: 100%;
}

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

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

Неверный идентификатор контейнера

HTML:

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

Jav * aScript:

container: 'map'

Возникает ошибка поиска элемента.

Названия должны совпадать:

container: 'my-map'

Неправильный порядок загрузки

Ошибка:

<script>
const map = new mapboxgl.Map(...);
</script>

<script src="mapbox-gl.js"></script>

В этот момент объект mapboxgl ещё не существует.

Правильный порядок:

<script src="mapbox-gl.js"></script>

<script>
const map = new mapboxgl.Map(...);
</script>

Преимущества CDN-подключения

Простота настройки

Не требуется установка пакетов и настройка среды разработки.

Быстрый запуск

Карта может быть отображена за несколько минут после создания HTML-файла.

Подходит для обучения

Весь код располагается в одном документе и легко анализируется.

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

Не нужны Webpack, Vite, Rollup или другие инструменты сборки.

Удобство прототипирования

Можно быстро проверять идеи без создания полноценной инфраструктуры проекта.

Ограничения CDN-подхода

По мере роста приложения начинают проявляться ограничения.

Нет модульной системы

Вместо:

import mapboxgl from 'mapbox-gl';

используется глобальный объект:

mapboxgl

Сложнее организовать большой проект

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

Ограниченный контроль над сборкой

Невозможно использовать возможности современных сборщиков:

  • tree shaking;
  • автоматическую оптимизацию;
  • разделение кода на чанки;
  • встроенную работу с TypeScript;
  • продвинутую минификацию.

Когда использовать CDN

Наиболее оправдано применение CDN-подключения в следующих случаях:

  • изучение Mapbox GL JS;
  • создание демонстрационных примеров;
  • подготовка учебных материалов;
  • быстрые эксперименты с картографическими данными;
  • разработка небольших веб-страниц с картой;
  • создание прототипов перед переходом к полноценному проекту на npm.

Для крупных приложений чаще применяется установка через пакетный менеджер и использование ES-модулей, однако понимание механизма CDN-подключения остаётся фундаментальной основой работы с Mapbox GL JS и позволяет быстро развернуть карту практически в любом HTML-документе.

Оглавление