Минимальный HTML-шаблон

Минимальная интеграция MapLibre GL JS требует корректной HTML-разметки, подключения стилей библиотеки, JavaScript-движка и обязательного контейнера для отрисовки карты. Даже в простейшем варианте важно соблюдение нескольких критичных условий: наличие блока под карту, фиксированная высота контейнера и инициализация через API Map.

Подключение зависимостей MapLibre GL JS

Библиотека MapLibre GL JS распространяется через CDN или пакетные менеджеры. Для минимального шаблона используется CDN-подключение стилей и скрипта.

Основные ресурсы:

  • CSS: визуальное оформление карты и UI-элементов
  • JS: логика рендеринга WebGL-карты

Минимальный HTML-шаблон

<!DOCTYPE html>
<html lang="ru">
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />

  <title>MapLibre GL JS Map</title>

  <!-- Подключение стилей MapLibre -->
  <link
    rel="stylesheet"
    href="https://unpkg.com/maplibre-gl@latest/dist/maplibre-gl.css"
  />

  <style>
    /* Обязательное правило: контейнер карты должен иметь высоту */
    html, body {
      margin: 0;
      height: 100%;
    }

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

<body>
  <!-- Контейнер карты -->
  <div id="map"></div>

  <!-- Подключение JavaScript библиотеки -->
  <script src="https://unpkg.com/maplibre-gl@latest/dist/maplibre-gl.js"></script>

  <script>
    const map = new maplibregl.Map({
      container: 'map',
      style: 'https://demotiles.maplibre.org/style.json',
      center: [37.6173, 55.7558],
      zoom: 10
    });
  </script>
</body>
</html>

Контейнер карты и требования к разметке

MapLibre GL JS использует WebGL-контекст, который привязывается к DOM-элементу. Ключевым элементом выступает контейнер:

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

Обязательные условия:

  • контейнер должен существовать до инициализации карты
  • контейнер обязан иметь ненулевые размеры
  • высота должна быть задана явно (через CSS)

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

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

MapLibre не управляет размерами страницы. Отображение зависит от CSS:

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

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

Варианты задания размеров

Фиксированная высота:

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

Относительная высота через flex-layout:

body {
  margin: 0;
  display: flex;
  flex-direction: column;
  height: 100vh;
}

#map {
  flex: 1;
}

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

Основной объект библиотеки — maplibregl.Map. Он принимает конфигурационный объект.

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

Параметры инициализации

  • container — идентификатор DOM-элемента или сам элемент
  • style — JSON-описание стиля карты
  • center — координаты [longitude, latitude]
  • zoom — начальный масштаб

Стиль карты

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

  • источники тайлов
  • слои (layers)
  • визуальное оформление объектов

В минимальном примере используется публичный демо-стиль:

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

Структура style.json (упрощённо)

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

Без корректного style JSON карта не отрисует данные.

Координатная система

MapLibre GL JS использует формат:

[longitude, latitude]

Пример:

center: [55.2708, 25.2048]

Ошибкой считается обратный порядок [lat, lng], приводящий к смещению отображения на глобусе.

Подключение через локальный сервер

При открытии HTML-файла напрямую через file:// могут возникать ограничения браузера:

  • блокировка CORS-запросов к style.json
  • невозможность загрузки тайлов

Используется локальный сервер:

npx serve .

или

python -m http.server 8080

Базовая структура выполнения

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

  1. загрузка HTML
  2. применение CSS (размер контейнера)
  3. загрузка maplibre-gl.js
  4. создание объекта Map
  5. загрузка style.json
  6. запрос тайлов
  7. отрисовка WebGL-карты

Типичные ошибки минимального шаблона

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

#map { width: 100%; }

Результат: пустой экран без ошибок в консоли.

Неверный путь к стилю

style: 'style.json'

Результат: ошибка загрузки источника данных.

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

center: [55.75, 37.61]

Результат: карта уходит в неверную точку.

Минимально допустимая версия шаблона

Без дополнительных стилей и параметров допустим следующий каркас:

<div id="map" style="width:100%;height:100vh;"></div>

<script src="https://unpkg.com/maplibre-gl@latest/dist/maplibre-gl.js"></script>
<script>
  new maplibregl.Map({
    container: 'map',
    style: 'https://demotiles.maplibre.org/style.json'
  });
</script>

Такой вариант демонстрирует минимальный объём кода, необходимый для запуска WebGL-карты.

Особенности WebGL-рендеринга в базовом шаблоне

MapLibre GL JS использует WebGL 2D/3D контекст, что означает:

  • отрисовка происходит на GPU
  • DOM используется только как контейнер
  • перерисовка зависит от состояния камеры (zoom, center, pitch)

Даже минимальный шаблон уже включает полноценный графический пайплайн, работающий поверх HTML-страницы.

Оглавление