Установка и настройка

MapLibre GL JS распространяется как npm-пакет и поддерживает интеграцию через современные сборщики модулей, а также подключение через CDN. Библиотека предназначена для рендеринга интерактивных карт с использованием WebGL и работает в браузерной среде.

Установка через npm

Основной способ подключения в проектах с модульной системой:

npm install maplibre-gl

или при использовании yarn:

yarn add maplibre-gl

После установки библиотека становится доступной для импорта в JavaScript или TypeScript коде:

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

Подключение CSS-файла является обязательным, поскольку он содержит базовые стили для контейнера карты, элементов управления и слоёв.

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

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

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

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

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

Перед созданием карты требуется HTML-элемент, который будет служить контейнером рендеринга WebGL:

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

Размер контейнера задаётся через CSS, так как без явных размеров карта не отобразится:

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

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

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

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

Основные параметры инициализации

  • container — идентификатор DOM-элемента или сам элемент
  • style — URL или объект стиля MapLibre Style Specification
  • center — координаты центра карты в формате [долгота, широта]
  • zoom — уровень масштабирования

Дополнительно могут задаваться:

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

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

MapLibre GL JS использует стили в формате JSON, соответствующие спецификации Mapbox Style Specification.

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

{
  "version": 8,
  "sources": {
    "osm": {
      "type": "raster",
      "tiles": [
        "https://tile.openstreetmap.org/{z}/{x}/{y}.png"
      ],
      "tileSize": 256
    }
  },
  "layers": [
    {
      "id": "osm-layer",
      "type": "raster",
      "source": "osm"
    }
  ]
}

Такой подход позволяет использовать любые тайловые серверы, включая OpenStreetMap, собственные tile-серверы или коммерческие провайдеры.

Использование с современными сборщиками

Vite

При использовании Vite установка остаётся стандартной, но требуется корректная работа с CSS:

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'
});

Vite автоматически обрабатывает зависимости и стили без дополнительной конфигурации.

Webpack

При Webpack может потребоваться настройка загрузчиков CSS:

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/,
        use: ['style-loader', 'css-loader']
      }
    ]
  }
};

После этого подключение идентично:

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

TypeScript

MapLibre GL JS содержит типизацию, что позволяет использовать строгую проверку типов:

import maplibregl from 'maplibre-gl';

const map: maplibregl.Map = new maplibregl.Map({
  container: 'map',
  style: 'https://demotiles.maplibre.org/style.json'
});

Работа с токенами и источниками данных

В отличие от некоторых картографических SDK, MapLibre GL JS не требует обязательного API-токена. Однако источники данных могут иметь собственные требования авторизации.

Пример использования защищённого тайлового сервера:

const map = new maplibregl.Map({
  container: 'map',
  style: {
    version: 8,
    sources: {
      tileset: {
        type: 'vector',
        tiles: [
          'https://example.com/tiles/{z}/{x}/{y}.pbf?key=API_KEY'
        ]
      }
    },
    layers: [
      {
        id: 'tileset-layer',
        type: 'fill',
        source: 'tileset'
      }
    ]
  }
});

Обработка загрузки карты

Для управления моментом полной инициализации используется событие load:

map.on('load', () => {
  map.addSource('points', {
    type: 'geojson',
    data: {
      type: 'FeatureCollection',
      features: []
    }
  });
});

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

Базовая структура приложения с MapLibre GL JS

Типовая структура проекта включает:

project/
  index.html
  main.js
  styles.css
  package.json

main.js:

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.addControl(new maplibregl.NavigationControl());

index.html:

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8" />
  <title>MapLibre</title>
  <link rel="stylesheet" href="styles.css" />
</head>
<body>
  <div id="map"></div>
  <script type="module" src="./main.js"></script>
</body>
</html>

Добавление стандартных элементов управления

Библиотека включает набор встроенных контролов:

map.addControl(new maplibregl.NavigationControl());
map.addControl(new maplibregl.ScaleControl());
map.addControl(new maplibregl.FullscreenControl());

Контролы добавляются после создания экземпляра карты и могут быть размещены в разных углах интерфейса.

Частые ошибки при установке и настройке

  • Отсутствие подключения CSS приводит к некорректному отображению интерфейса
  • Неверно заданный контейнер без размеров блокирует рендеринг карты
  • Использование неподдерживаемых или некорректных style.json вызывает ошибки загрузки слоёв
  • Попытка добавления источников до события load приводит к исключениям
  • Неправильный порядок координат [lng, lat] и [lat, lng] приводит к смещению центра карты
Оглавление