Установка и подключение

Подключение библиотеки начинается с добавления стилей и JavaScript-файла Mapbox GL JS от Mapbox. Библиотека работает в связке с CSS, без которого карта не будет корректно отображаться.

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

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

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

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

Карта всегда привязывается к DOM-элементу фиксированной высоты. Без заданной высоты контейнер останется невидимым.

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

Ключевое требование: контейнер должен иметь явные размеры до инициализации карты.

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

Любая работа с Mapbox GL JS требует access token, выдаваемого в панели управления Mapbox.

mapboxgl.accessToken = "YOUR_ACCESS_TOKEN";

Токен используется для авторизации запросов к тайлам, стилям и API-ресурсам.

Официальная документация и получение ключа: Mapbox official website

Инициализация карты

Базовая инициализация создаёт интерактивную карту с заданным стилем и координатами центра.

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

Основные параметры:

  • container — ID HTML-элемента
  • style — стиль карты (URL Mapbox Style)
  • center — координаты [lng, lat]
  • zoom — масштаб отображения

Важно учитывать порядок координат: сначала долгота, затем широта.

Подключение через npm

Для современных проектов используется пакетная установка через npm.

npm install mapbox-gl

Импорт в модуле:

import mapboxgl from "mapbox-gl";
import "mapbox-gl/dist/mapbox-gl.css";

mapboxgl.accessToken = "YOUR_ACCESS_TOKEN";

const map = new mapboxgl.Map({
  container: "map",
  style: "mapbox://styles/mapbox/light-v11",
  center: [69.2401, 41.2995],
  zoom: 12
});

Такой способ обязателен при использовании Vite, Webpack, Rollup или других сборщиков.

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

При использовании сборщиков важно учитывать корректную обработку CSS и ассетов.

Vite

import mapboxgl from "mapbox-gl";
import "mapbox-gl/dist/mapbox-gl.css";

Vite автоматически обрабатывает стили без дополнительных лоадеров.

Webpack

Для Webpack требуется CSS loader:

npm install css-loader style-loader --save-dev
module: {
  rules: [
    {
      test: /\.css$/,
      use: ["style-loader", "css-loader"]
    }
  ]
}

Стили карты

Mapbox использует стилевую систему, основанную на JSON-конфигурациях.

Примеры встроенных стилей:

style: "mapbox://styles/mapbox/streets-v12"
style: "mapbox://styles/mapbox/outdoors-v12"
style: "mapbox://styles/mapbox/light-v11"
style: "mapbox://styles/mapbox/dark-v11"

Стиль определяет:

  • визуализацию дорог и зданий
  • цветовую палитру
  • слои данных
  • типографику

Проверка загрузки карты

Инициализация проходит асинхронно. Для выполнения логики после полной загрузки используется событие:

map.on("load", () => {
  console.log("Карта загружена");
});

Событие load гарантирует, что все слои и тайлы уже доступны.

Частые ошибки при подключении

Отсутствие CSS

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

Неуказанный контейнер

container: "map"

Элемент с таким ID обязан существовать в DOM до инициализации.

Неверный токен

Ошибки авторизации приводят к пустой карте и сообщениям в консоли:

  • 401 Unauthorized
  • Not Authorized

Нарушение порядка координат

Mapbox использует формат:

[longitude, latitude]

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

Минимальная рабочая конфигурация

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8" />
  <link href="https://api.mapbox.com/mapbox-gl-js/v3.7.0/mapbox-gl.css" rel="stylesheet" />
  <style>
    body { margin: 0; }
    #map { height: 100vh; width: 100%; }
  </style>
</head>
<body>

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

<script src="https://api.mapbox.com/mapbox-gl-js/v3.7.0/mapbox-gl.js"></script>
<script>
  mapboxgl.accessToken = "YOUR_ACCESS_TOKEN";

  const map = new mapboxgl.Map({
    container: "map",
    style: "mapbox://styles/mapbox/streets-v12",
    center: [69.2401, 41.2995],
    zoom: 11
  });
</script>

</body>
</html>
Оглавление