Инициализация экземпляра карты

Инициализация экземпляра карты в MapLibre GL JS начинается с подготовки DOM-элемента, который будет служить контейнером для WebGL-контекста. Контейнер обязан существовать в момент создания карты, поскольку библиотека напрямую привязывает рендеринг к указанному HTML-элементу.

Типовая разметка:

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

Ключевым требованием является наличие явных размеров. Без заданной высоты контейнер останется нулевой высоты, и карта не будет отображена.

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

Важный момент: MapLibre GL использует WebGL, поэтому контейнер не должен быть скрыт (display: none) на момент инициализации.

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

Библиотека может быть подключена через CDN или установлена как модуль в сборщике.

CDN-вариант:

<link href="https://unpkg.com/maplibre-gl/dist/maplibre-gl.css" rel="stylesheet" />
<script src="https://unpkg.com/maplibre-gl/dist/maplibre-gl.js"></script>

Модульный вариант:

import maplibregl from 'maplibre-gl';
import 'maplibre-gl/dist/maplibre-gl.css';

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

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

Основная точка входа — конструктор Map.

const map = new maplibregl.Map({
  container: 'map',
  style: 'https://demotiles.maplibre.org/style.json',
  center: [30.31413, 59.93863],
  zoom: 10
});

Параметр container

container определяет DOM-элемент, в который будет встроен WebGL canvas. Возможны варианты:

  • строка — идентификатор элемента
  • HTMLElement — прямой DOM-узел
container: document.getElementById('map')

При ошибке в выборе контейнера карта не инициализируется и выбрасывает исключение.

Параметр style

style задаёт источник описания визуального стиля карты. Это JSON-спецификация, включающая слои, источники данных, фильтры и стилизацию.

Пример URL:

style: 'https://demotiles.maplibre.org/style.json'

Также возможна передача объекта:

style: {
  version: 8,
  sources: {},
  layers: []
}

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

  • источники тайлов
  • набор слоёв (layers)
  • типы визуализации (fill, line, circle, symbol)
  • шрифты и спрайты

Отсутствие корректного style приводит к пустому рендеру даже при корректной инициализации карты.

Параметры центра и масштаба

center

center задаёт начальную географическую позицию в формате [longitude, latitude].

center: [30.31413, 59.93863]

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

zoom

zoom определяет масштаб отображения:

  • 0 — глобальный уровень
  • 5–10 — региональный уровень
  • 10–15 — городской уровень
  • 15+ — уличный уровень
zoom: 12

Расширенная конфигурация экземпляра

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

maxZoom и minZoom

Ограничивают диапазон масштабирования:

minZoom: 3,
maxZoom: 18

Это полезно при создании специализированных карт, где детализация ограничена данными.

bearing и pitch

bearing

Определяет поворот карты:

bearing: 30

Значение задаётся в градусах по часовой стрелке.

pitch

Задаёт наклон камеры:

pitch: 45

Используется для 3D-эффектов, особенно при визуализации зданий.

antialias и renderWorldCopies

antialias

antialias: true

Включает сглаживание линий и полигонов. Увеличивает качество визуализации, но может снижать производительность.

renderWorldCopies

renderWorldCopies: true

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

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

Инициализация карты не является мгновенной операцией. После создания экземпляра начинается загрузка стиля, источников и ресурсов.

Ключевое событие:

map.on('load', () => {
  // карта полностью готова
});

Стадии загрузки включают:

  1. создание WebGL context
  2. загрузка style.json
  3. загрузка источников тайлов
  4. инициализация слоёв
  5. подготовка текстур и шрифтов

До события load работа с слоями и источниками ограничена.

Работа с ошибками при инициализации

MapLibre генерирует события ошибок, которые важно отслеживать:

map.on('error', (e) => {
  console.error(e.error);
});

Типичные причины ошибок:

  • недоступный style URL
  • CORS-ограничения на тайлы
  • некорректный JSON стиля
  • отсутствие WebGL поддержки

Динамическая инициализация контейнера

В приложениях с динамическим интерфейсом контейнер может появляться после загрузки DOM.

Корректный подход:

document.addEventListener('DOMContentLoaded', () => {
  const map = new maplibregl.Map({
    container: 'map',
    style: 'https://demotiles.maplibre.org/style.json',
    center: [30, 60],
    zoom: 5
  });
});

Если контейнер создаётся позже (например, в SPA), инициализация должна выполняться после его вставки в DOM.

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

Экземпляр карты является тяжёлым объектом, связанный с WebGL контекстом. Повторная инициализация без уничтожения предыдущего экземпляра приводит к утечкам ресурсов.

Корректное освобождение:

map.remove();

После вызова remove WebGL контекст уничтожается, а DOM-узел очищается от canvas.

Инициализация без стиля

В некоторых случаях карта создаётся без немедленной загрузки стиля:

const map = new maplibregl.Map({
  container: 'map',
  center: [0, 0],
  zoom: 2,
  style: null
});

Позднее стиль может быть установлен:

map.setStyle('https://demotiles.maplibre.org/style.json');

Это используется для сценариев, где стиль зависит от пользовательских настроек или внешних данных.

Использование кастомных координатных систем

MapLibre GL работает в Web Mercator по умолчанию, но инициализация может учитывать нестандартные источники данных через projection:

maplibregl.setRTLTextPlugin(
  'https://api.mapbox.com/mapbox-gl-js/plugins/mapbox-gl-rtl-text/v0.2.3/mapbox-gl-rtl-text.js'
);

Хотя это не влияет напрямую на конструктор, такие настройки часто выполняются до создания экземпляра карты.

Производительность при старте

Инициализация карты напрямую связана с:

  • количеством слоёв в стиле
  • количеством источников данных
  • размером спрайтов и шрифтов
  • включением 3D-параметров (pitch, terrain)

Оптимизация заключается в минимизации стиля на этапе загрузки и последующей догрузке слоёв через API.

Контроль готовности рендера

Помимо события load, существует событие idle, которое сигнализирует о полной стабилизации рендера:

map.on('idle', () => {
  // карта полностью отрисована и не выполняет загрузку
});

Это важно для сценариев автоматизированного тестирования или генерации скриншотов.

Интеграция с внешними состояниями

Инициализация часто связывается с состоянием приложения:

const map = new maplibregl.Map({
  container: 'map',
  style: currentThemeStyle,
  center: userLocation,
  zoom: userZoom
});

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

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

Повторная инициализация и смена стиля

Изменение стиля после создания карты не требует пересоздания экземпляра:

map.setStyle('https://example.com/new-style.json');

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

Особенности работы в SPA

В одностраничных приложениях важно учитывать:

  • уничтожение экземпляра при размонтировании компонента
  • предотвращение повторного создания карты в одном контейнере
  • синхронизацию состояния маршрутизатора с положением карты

Типичная ошибка — создание нового экземпляра при каждом переходе без вызова remove.

Минимальный корректный шаблон инициализации

import maplibregl from 'maplibre-gl';
import 'maplibre-gl/dist/maplibre-gl.css';

const map = new maplibregl.Map({
  container: 'map',
  style: 'https://demotiles.maplibre.org/style.json',
  center: [0, 0],
  zoom: 2
});

map.on('load', () => {
  map.resize();
});
Оглавление