Базовые параметры конструктора

Инициализация карты в MapLibre GL JS выполняется через создание экземпляра объекта Map, который принимает конфигурационный объект с набором параметров, определяющих поведение, внешний вид и взаимодействие с картой. Именно на уровне конструктора задаётся фундаментальная структура сцены, источники данных и параметры пользовательского взаимодействия.

import maplibregl from "maplibre-gl";

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

container — целевой DOM-элемент

Параметр container определяет HTML-элемент, в который будет встроена карта. Он может быть задан строкой (идентификатор элемента) или непосредственно DOM-узлом.

container: "map"

или

container: document.getElementById("map")

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

  • элемент должен существовать в DOM на момент инициализации;
  • контейнер должен иметь явные размеры (ширина и высота), иначе карта не отобразится;
  • внутри контейнера MapLibre создаёт собственный canvas и служебные слои.

style — описание визуального стиля карты

Параметр style определяет источник и структуру визуального оформления карты. Это JSON-объект или URL, указывающий на Style Specification.

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

Возможные варианты:

  • URL к стилю;
  • объект стиля, загруженный заранее;
  • локально определённый JSON.

Стиль включает:

  • источники данных (sources);
  • слои (layers);
  • спрайты и glyphs;
  • правила визуализации геометрии.

center — начальная позиция карты

Параметр center задаёт координаты центра карты в момент инициализации.

center: [longitude, latitude]

Пример:

center: [37.6173, 55.7558]

Особенности:

  • порядок координат строго [долгота, широта];
  • используется система WGS84;
  • влияет на начальную камеру, но может быть изменён динамически.

zoom — уровень масштабирования

Параметр zoom определяет начальный масштаб отображения карты.

zoom: 10

Характеристики:

  • значения обычно находятся в диапазоне от 0 до 24+;
  • дробные значения поддерживаются;
  • увеличение zoom приближает карту, уменьшение — отдаляет.

bearing — угол поворота карты

Параметр bearing задаёт азимут вращения карты в градусах.

bearing: 0

Свойства:

  • 0° — север вверх;
  • положительные значения вращают карту по часовой стрелке;
  • используется для создания 3D-ориентации сцены.

pitch — наклон камеры

Параметр pitch управляет наклоном карты относительно горизонта.

pitch: 45

Особенности:

  • измеряется в градусах;
  • 0° — вид сверху;
  • максимальные значения обычно до 60–70°;
  • применяется для создания псевдо-3D визуализации.

minZoom и maxZoom — ограничения масштабирования

Эти параметры задают допустимый диапазон масштабирования.

minZoom: 3,
maxZoom: 18

Поведение:

  • ограничивают пользовательский zoom;
  • влияют на доступность тайлов;
  • предотвращают чрезмерное приближение или удаление.

maxBounds — ограничение области перемещения

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

maxBounds: [
    [30, 50],
    [40, 60]
]

Структура:

  • два угла прямоугольника: юго-западный и северо-восточный;
  • координаты задаются в формате [lng, lat].

Применение:

  • ограничение отображения региона;
  • предотвращение выхода за заданные географические границы.

hash — синхронизация состояния с URL

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

hash: true

Поведение:

  • сохраняет zoom, center, bearing в URL;
  • позволяет делиться ссылками на текущее положение карты;
  • полезен для навигационных приложений.

interactive — управление взаимодействием

Параметр interactive включает или отключает пользовательское взаимодействие.

interactive: true

При значении false отключаются:

  • панорамирование;
  • масштабирование;
  • вращение;
  • обработка событий мыши и тач-интерфейса.

attributionControl — контроль атрибуции

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

attributionControl: true

Особенности:

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

renderWorldCopies — копирование мира

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

renderWorldCopies: true

Поведение:

  • true — бесконечная прокрутка по долготе;
  • false — ограничение одним миром.

transformRequest — перехват сетевых запросов

Позволяет модифицировать все запросы к ресурсам карты (тайлы, стили, шрифты, спрайты).

transformRequest: (url, resourceType) => {
    return {
        url,
        headers: {
            "Authorization": "Bearer TOKEN"
        }
    };
}

Возможности:

  • добавление заголовков авторизации;
  • подмена URL;
  • логирование запросов;
  • интеграция с защищёнными API.

projection — система проекции

Параметр projection задаёт тип географической проекции.

projection: "mercator"

Поддерживаемые варианты:

  • mercator — стандартная Web Mercator;
  • globe — сферическая проекция (в новых версиях).

Влияние:

  • меняет способ отображения координат;
  • влияет на рендеринг и перспективу;
  • определяет поведение камеры.

cooperativeGestures — режим совместного взаимодействия

Позволяет требовать дополнительное действие пользователя для взаимодействия с картой (например, Ctrl + scroll).

cooperativeGestures: true

Применение:

  • предотвращение случайного зума при прокрутке страницы;
  • улучшение UX в встроенных картах.

fadeDuration — время анимации переходов

Определяет длительность плавных переходов при смене тайлов и слоёв.

fadeDuration: 300

Особенности:

  • значение в миллисекундах;
  • влияет на визуальную плавность загрузки данных;
  • может быть уменьшено для повышения отзывчивости.

collectResourceTiming — сбор метрик производительности

Включает сбор данных о загрузке ресурсов карты.

collectResourceTiming: true

Используется для:

  • анализа производительности;
  • профилирования загрузки тайлов;
  • оптимизации рендеринга.

refreshExpiredTiles — обновление устаревших тайлов

Контролирует автоматическое обновление устаревших данных.

refreshExpiredTiles: true

Поведение:

  • при true карта запрашивает актуальные тайлы;
  • при false используются кешированные данные.

localIdeographFontFamily — шрифты для CJK символов

Параметр задаёт семейство шрифтов для иероглифических языков.

localIdeographFontFamily: "Noto Sans CJK"

Назначение:

  • улучшение рендеринга китайских, японских и корейских символов;
  • уменьшение зависимости от загружаемых glyph-тайлов.

crossSourceCollisions и collision behavior

Управляют поведением столкновений символов между слоями.

crossSourceCollisions: true

Эффекты:

  • объединение логики столкновений разных источников;
  • более плотная отрисовка подписей;
  • влияние на читаемость карты при высокой загрузке.

Общая структура конфигурационного объекта

Типовая конфигурация конструктора объединяет несколько параметров одновременно, формируя полную модель карты:

const map = new maplibregl.Map({
    container: "map",
    style: "style.json",
    center: [0, 0],
    zoom: 2,
    bearing: 0,
    pitch: 0,
    minZoom: 1,
    maxZoom: 18,
    maxBounds: [[-180, -85], [180, 85]],
    hash: true,
    interactive: true,
    attributionControl: true,
    renderWorldCopies: true
});
Оглавление