Map класс

Класс Map является центральным объектом библиотеки MapLibre GL JS. Через него выполняется создание карты, управление отображением данных, настройка взаимодействия пользователя, работа со слоями, источниками данных, событиями, анимацией и камерой.

Практически любой сценарий работы с MapLibre начинается с создания экземпляра класса Map.

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

После создания объекта становится доступен широкий набор методов и свойств для управления картой.

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

Конструктор принимает объект настроек.

const map = new maplibregl.Map(options);

Наиболее часто используемые параметры:

Параметр	Описание
`container`	HTML-элемент или его идентификатор
`style`	URL стиля или объект стиля
`center`	Начальные координаты центра
`zoom`	Начальный масштаб
`bearing`	Угол поворота карты
`pitch`	Наклон карты
`hash`	Синхронизация состояния карты с URL
`interactive`	Разрешение взаимодействия пользователя
`antialias`	Сглаживание WebGL
`maxZoom`	Максимальный масштаб
`minZoom`	Минимальный масштаб

Пример полной конфигурации:

const map = new maplibregl.Map({
    container: 'map',
    style: 'https://demotiles.maplibre.org/style.json',
    center: [30.3141, 59.9386],
    zoom: 12,
    pitch: 45,
    bearing: 20,
    minZoom: 5,
    maxZoom: 18,
    antialias: true
});

Контейнер карты

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

HTML:

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

CSS:

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

Jav * aScript:

const map = new maplibregl.Map({
    container: 'map',
    style: styleUrl
});

Допускается передача самого элемента:

const container = document.getElementById('map');

const map = new maplibregl.Map({
    container
});

Параметры камеры

Камера определяет текущее положение наблюдателя.

center

Координаты центра карты.

center: [37.6176, 55.7558]

Получение текущего центра:

const center = map.getCenter();

console.log(center.lng);
console.log(center.lat);

Изменение центра:

map.setCenter([30.3141, 59.9386]);

zoom

Уровень масштабирования.

zoom: 8

Получение текущего масштаба:

const zoom = map.getZoom();

Установка нового масштаба:

map.setZoom(12);

bearing

Поворот карты относительно севера.

bearing: 45

Получение значения:

const bearing = map.getBearing();

Изменение:

map.setBearing(90);

pitch

Наклон карты.

pitch: 60

Получение:

const pitch = map.getPitch();

Изменение:

map.setPitch(45);

Методы управления камерой

jumpTo()

Мгновенно изменяет положение карты.

map.jumpTo({
    center: [37.6176, 55.7558],
    zoom: 12
});

Переход происходит без анимации.

easeTo()

Плавное перемещение камеры.

map.easeTo({
    center: [37.6176, 55.7558],
    zoom: 13,
    duration: 3000
});

Основные параметры:

Параметр	Описание
`center`	Новый центр
`zoom`	Новый масштаб
`bearing`	Новый угол
`pitch`	Новый наклон
`duration`	Продолжительность

flyTo()

Имитация полёта камеры.

map.flyTo({
    center: [37.6176, 55.7558],
    zoom: 14
});

Часто используется для навигации между удалёнными объектами.

map.flyTo({
    center: [2.3522, 48.8566],
    zoom: 12,
    speed: 0.8,
    curve: 1.5
});

fitBounds()

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

map.fitBounds([
    [37.55, 55.70],
    [37.75, 55.85]
]);

С отступами:

map.fitBounds(
    [
        [37.55, 55.70],
        [37.75, 55.85]
    ],
    {
        padding: 50
    }
);

Получение текущего состояния карты

Получение масштаба

const zoom = map.getZoom();

Получение центра

const center = map.getCenter();

Получение наклона

const pitch = map.getPitch();

Получение поворота

const bearing = map.getBearing();

Получение границ

const bounds = map.getBounds();

Пример:

console.log(bounds.getWest());
console.log(bounds.getEast());
console.log(bounds.getNorth());
console.log(bounds.getSouth());

Изменение размеров карты

После изменения размеров контейнера необходимо уведомить карту.

map.resize();

Типичный пример:

window.addEventListener('resize', () => {
    map.resize();
});

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

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

Получение стиля

const style = map.getStyle();

Замена стиля

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

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

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

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

Добавление GeoJSON-источника:

map.addSource('cities', {
    type: 'geojson',
    data: 'cities.geojson'
});

Локальные данные:

map.addSource('cities', {
    type: 'geojson',
    data: {
        type: 'FeatureCollection',
        features: []
    }
});

Проверка существования источника

const source = map.getSource('cities');

Проверка:

if (map.getSource('cities')) {
    console.log('Источник существует');
}

Удаление источника

map.removeSource('cities');

Перед удалением необходимо удалить связанные слои.

Работа со слоями

Слой определяет способ отображения данных.

Добавление слоя:

map.addLayer({
    id: 'cities-layer',
    type: 'circle',
    source: 'cities',
    paint: {
        'circle-radius': 6,
        'circle-color': '#ff0000'
    }
});

Получение слоя

const layer = map.getLayer('cities-layer');

Проверка существования

if (map.getLayer('cities-layer')) {
    console.log('Слой найден');
}

Удаление слоя

map.removeLayer('cities-layer');

Перемещение слоя

map.moveLayer('cities-layer');

Размещение перед другим слоем:

map.moveLayer(
    'cities-layer',
    'roads-layer'
);

Изменение свойств слоя

setPaintProperty()

Изменение визуального оформления.

map.setPaintProperty(
    'cities-layer',
    'circle-color',
    '#00ff00'
);

Изменение радиуса:

map.setPaintProperty(
    'cities-layer',
    'circle-radius',
    10
);

setLayoutProperty()

Изменение параметров компоновки.

map.setLayoutProperty(
    'cities-layer',
    'visibility',
    'none'
);

Показ слоя:

map.setLayoutProperty(
    'cities-layer',
    'visibility',
    'visible'
);

Получение объектов карты

queryRenderedFeatures()

Поиск объектов, которые отображаются на экране.

const features =
    map.queryRenderedFeatures();

Поиск в определённой точке:

const features =
    map.queryRenderedFeatures(
        [300, 200]
    );

Поиск по слоям:

const features =
    map.queryRenderedFeatures({
        layers: ['cities-layer']
    });

querySourceFeatures()

Получение объектов непосредственно из источника.

const features =
    map.querySourceFeatures(
        'cities'
    );

Данный метод не зависит от текущего отображения карты.

События карты

Класс Map наследует систему событий.

map.on('click', (event) => {
    console.log(event.lngLat);
});

Отписка:

map.off('click', handler);

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

map.once('load', () => {
    console.log('Карта загружена');
});

Основные события

load

Полная загрузка карты.

map.on('load', () => {
    console.log('Ready');
});

click

Щелчок мышью.

map.on('click', (e) => {
    console.log(e.lngLat);
});

dblclick

Двойной щелчок.

map.on('dblclick', (e) => {
    console.log(e.point);
});

mousemove

Движение указателя.

map.on('mousemove', (e) => {
    console.log(e.lngLat);
});

move

Любое перемещение карты.

map.on('move', () => {
    console.log(map.getCenter());
});

zoom

Изменение масштаба.

map.on('zoom', () => {
    console.log(map.getZoom());
});

rotate

Поворот карты.

map.on('rotate', () => {
    console.log(map.getBearing());
});

pitch

Изменение наклона.

map.on('pitch', () => {
    console.log(map.getPitch());
});

idle

Срабатывает после завершения всех операций рендеринга.

map.on('idle', () => {
    console.log('Карта полностью готова');
});

Работа с элементами управления

Добавление навигации:

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

Добавление полноэкранного режима:

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

Добавление геолокации:

map.addControl(
    new maplibregl.GeolocateControl()
);

Размещение в конкретной позиции:

map.addControl(
    new maplibregl.NavigationControl(),
    'top-right'
);

Доступные позиции:

top-left
top-right
bottom-left
bottom-right

Преобразование координат

project()

Преобразует географические координаты в пиксели.

const point = map.project([
    37.6176,
    55.7558
]);

Результат:

console.log(point.x);
console.log(point.y);

unproject()

Преобразует экранные координаты в географические.

const lngLat = map.unproject([
    500,
    300
]);

Проверка состояния карты

loaded()

Проверяет завершение загрузки.

if (map.loaded()) {
    console.log('Карта загружена');
}

isStyleLoaded()

Проверяет готовность стиля.

if (map.isStyleLoaded()) {
    console.log('Стиль загружен');
}

isMoving()

Проверяет наличие движения камеры.

if (map.isMoving()) {
    console.log('Карта перемещается');
}

isZooming()

Проверяет изменение масштаба.

if (map.isZooming()) {
    console.log('Выполняется масштабирование');
}

isRotating()

Проверяет вращение карты.

if (map.isRotating()) {
    console.log('Карта вращается');
}

Уничтожение карты

При удалении компонента интерфейса рекомендуется освобождать ресурсы.

map.remove();

После вызова метода:

удаляются обработчики событий;
освобождаются ресурсы WebGL;
удаляются элементы управления;
прекращается рендеринг карты.

Особенно важно вызывать remove() в SPA-приложениях на React, Vue, Angular и других фреймворках для предотвращения утечек памяти.

Практический пример

Ниже приведён пример создания карты с источником данных, слоем и анимированным перемещением камеры.

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

map.on('load', () => {

    map.addSource('city', {
        type: 'geojson',
        data: {
            type: 'Feature',
            geometry: {
                type: 'Point',
                coordinates: [
                    37.6176,
                    55.7558
                ]
            }
        }
    });

    map.addLayer({
        id: 'city-layer',
        type: 'circle',
        source: 'city',
        paint: {
            'circle-radius': 10,
            'circle-color': '#ff0000'
        }
    });

    map.flyTo({
        center: [37.6176, 55.7558],
        zoom: 12,
        pitch: 45,
        bearing: 30,
        duration: 4000
    });
});

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