Инициализация объекта карты

Mapbox GL JS требует наличия подключённой JavaScript-библиотеки и CSS-стилей, обеспечивающих корректное отображение карты. Основной ресурс библиотеки загружается через CDN или устанавливается через пакетный менеджер:

<link href="https://api.mapbox.com/mapbox-gl-js/v2.15.0/mapbox-gl.css" rel="stylesheet" />
<script src="https://api.mapbox.com/mapbox-gl-js/v2.15.0/mapbox-gl.js"></script>

Ключевым элементом является DOM-контейнер, в котором будет отрисована карта. Он обязан иметь явно заданные размеры, иначе WebGL-контекст не сможет корректно инициализироваться:

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

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

Отсутствие высоты — одна из наиболее частых причин пустого экрана при инициализации карты.

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

Mapbox GL JS требует авторизации через access token. Он задаётся глобально через объект библиотеки:

mapboxgl.accessToken = 'pk.your_access_token_here';

Токен определяет доступ к стилям, тайлам и API сервиса. Без него создание экземпляра карты завершится ошибкой загрузки ресурсов.

Создание экземпляра карты

Основной объект карты создаётся через конструктор mapboxgl.Map. Именно он инициирует WebGL-рендеринг, загрузку стиля и построение сцены:

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

container

Параметр container определяет DOM-элемент, в котором будет размещена карта. Допускается передача ID строки или самого DOM-узла:

container: document.getElementById('map')

style

style задаёт визуальное оформление карты. Это может быть:

  • URL Mapbox-стиля
  • локальный JSON-стиль
  • кастомный стиль, совместимый со спецификацией Mapbox Style

Пример стандартного стиля:

style: 'mapbox://styles/mapbox/light-v11'

Центрирование и масштабирование

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

center

Координаты центра карты передаются в формате [долгота, широта]:

center: [73.3, 49.8]

Порядок координат строго фиксирован: сначала longitude, затем latitude.

zoom

Параметр zoom определяет уровень приближения:

zoom: 12

Малые значения показывают глобальный обзор, большие — детализацию улиц и объектов.

Дополнительные параметры камеры

Mapbox GL JS предоставляет расширенные настройки положения и ориентации камеры.

bearing

Определяет поворот карты относительно севера:

bearing: 30

pitch

Устанавливает наклон камеры:

pitch: 45

Комбинация pitch и bearing используется для создания 3D-эффекта и псевдо-объёмного восприятия сцены.

Ограничение области просмотра

Для управления границами перемещения карты применяется maxBounds:

maxBounds: [
  [73.0, 49.0],
  [74.0, 50.0]
]

Этот параметр ограничивает область панорамирования, фиксируя камеру внутри заданного прямоугольника.

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

Параметры minZoom и maxZoom ограничивают допустимые уровни приближения:

minZoom: 5,
maxZoom: 18

Ограничение полезно при необходимости скрыть чрезмерную детализацию или глобальный обзор.

Управление интерфейсом и поведением

attributionControl

Отвечает за отображение атрибуции:

attributionControl: true

renderWorldCopies

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

renderWorldCopies: true

При отключении глобус отображается без повторяющихся копий мира.

hash

Синхронизирует состояние карты с URL:

hash: true

Параметры центра и масштаба отображаются в адресной строке, что упрощает сохранение состояния.

Жизненный цикл и событие загрузки стиля

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

map.on('load', () => {
  map.addLayer({
    id: 'points',
    type: 'circle',
    source: {
      type: 'geojson',
      data: {
        type: 'FeatureCollection',
        features: []
      }
    },
    paint: {
      'circle-radius': 6,
      'circle-color': '#ff0000'
    }
  });
});

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

Деструктуризация и удаление карты

Освобождение ресурсов WebGL выполняется через метод remove:

map.remove();

Удаление карты критично при работе в SPA-архитектуре, где компоненты создаются и уничтожаются динамически. Игнорирование этого шага приводит к утечкам памяти и зависанию GPU-контекста.

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

В одном приложении может существовать несколько экземпляров карты, однако каждый должен иметь уникальный контейнер:

const mapA = new mapboxgl.Map({
  container: 'mapA',
  style: 'mapbox://styles/mapbox/streets-v12'
});

const mapB = new mapboxgl.Map({
  container: 'mapB',
  style: 'mapbox://styles/mapbox/dark-v11'
});

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

Типовые ошибки при инициализации

Частые проблемы связаны не с API, а с окружением:

  • отсутствие высоты контейнера
  • неверный access token
  • использование координат в неправильном порядке
  • попытка модификации карты до события load
  • повторная инициализация без remove

Корректная последовательность инициализации и контроль жизненного цикла объекта карты критичны для стабильной работы WebGL-рендеринга.

Оглавление