Установка уровня зума

Уровень зума (zoom level) в MapLibre GL JS определяет масштаб отображаемой карты. Чем выше значение зума, тем ближе отображается поверхность Земли и тем больше деталей становится доступно. При уменьшении значения карта отдаляется, охватывая более крупные территории.

Уровень зума представляет собой число с плавающей точкой. Это означает, что карта может находиться не только на целых значениях масштаба, таких как 5, 10 или 15, но и на промежуточных, например 8.5 или 12.75.

Типичные диапазоны масштабирования:

Zoom	Описание
0	Весь мир
1–4	Континенты и крупные страны
5–8	Регионы и области
9–12	Города
13–16	Районы и улицы
17–20+	Здания и отдельные объекты

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

Установка начального уровня зума

Начальный масштаб задаётся через параметр zoom при создании объекта карты.

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

После загрузки карта будет отображаться с масштабом 10.

В данном примере:

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

Использование дробных значений

MapLibre GL JS поддерживает плавное масштабирование благодаря дробным значениям.

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

Такой подход обеспечивает более точную настройку отображения карты.

Например:

zoom: 8.3

или

zoom: 14.75

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

Получение текущего уровня зума

Для получения текущего масштаба используется метод getZoom().

const zoom = map.getZoom();

console.log(zoom);

Результат:

12.483729201

Возвращаемое значение может содержать большое количество знаков после запятой.

Для отображения пользователю обычно выполняют округление:

const zoom = map.getZoom();

console.log(zoom.toFixed(2));

Результат:

12.48

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

Метод setZoom() позволяет мгновенно установить новый уровень масштабирования.

map.setZoom(15);

После выполнения карта сразу приблизится к уровню 15.

Изменение масштаба может выполняться в обработчиках событий:

button.addEventListener('click', () => {
    map.setZoom(8);
});

Плавное изменение масштаба

Для создания анимации используется метод zoomTo().

map.zoomTo(14);

Карта плавно перейдёт к новому масштабу.

Дополнительные параметры позволяют настроить длительность анимации:

map.zoomTo(14, {
    duration: 3000
});

Здесь переход займёт 3 секунды.

Масштабирование относительно точки

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

map.zoomTo(16, {
    around: [37.6176, 55.7558]
});

В этом случае карта приблизится к указанным координатам.

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

Одновременное изменение центра и масштаба

Метод jumpTo() позволяет изменить несколько параметров отображения сразу.

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

Изменение произойдёт без анимации.

Для анимированного перехода используется easeTo():

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

Ограничение минимального масштаба

Во многих приложениях необходимо запретить чрезмерное отдаление карты.

Для этого используется параметр minZoom.

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

Теперь пользователь не сможет уменьшить масштаб ниже уровня 5.

Ограничение максимального масштаба

Аналогично задаётся максимальное приближение.

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

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

Изменение ограничений после создания карты

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

Установка минимального значения:

map.setMinZoom(4);

Установка максимального значения:

map.setMaxZoom(20);

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

console.log(map.getMinZoom());
console.log(map.getMaxZoom());

Масштабирование на один уровень

Для пошагового управления масштабом удобно использовать методы увеличения и уменьшения.

Увеличение:

map.zoomIn();

Уменьшение:

map.zoomOut();

Пример привязки к кнопкам интерфейса:

document
    .getElementById('zoom-in')
    .addEventListener('click', () => {
        map.zoomIn();
    });

document
    .getElementById('zoom-out')
    .addEventListener('click', () => {
        map.zoomOut();
    });

Управление величиной шага масштабирования

Методы zoomIn() и zoomOut() принимают количество уровней изменения.

Увеличение на два уровня:

map.zoomIn({
    zoomDelta: 2
});

Уменьшение на полтора уровня:

map.zoomOut({
    zoomDelta: 1.5
});

Это позволяет создавать собственные сценарии навигации.

Отслеживание изменения масштаба

Во время изменения уровня зума генерируется событие zoom.

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

Обработчик будет вызываться непрерывно в процессе масштабирования.

Такой подход полезен для:

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

Событие завершения масштабирования

Если требуется выполнить действие только после завершения изменения масштаба, используется событие zoomend.

map.on('zoomend', () => {
    console.log('Масштабирование завершено');
});

Пример получения итогового масштаба:

map.on('zoomend', () => {
    const zoom = map.getZoom();

    console.log(`Текущий zoom: ${zoom}`);
});

Изменение отображения объектов в зависимости от масштаба

Многие карты используют разные представления данных на разных уровнях зума.

Пример:

map.on('zoomend', () => {
    const zoom = map.getZoom();

    if (zoom < 10) {
        console.log('Показывать только крупные объекты');
    } else {
        console.log('Показывать все объекты');
    }
});

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

Автоматическое приближение к объекту

После выбора объекта карта может автоматически изменять масштаб.

function focusObject(lng, lat) {
    map.flyTo({
        center: [lng, lat],
        zoom: 16
    });
}

Вызов:

focusObject(37.6176, 55.7558);

Метод flyTo() создаёт эффект плавного полёта камеры.

Масштабирование по границам объекта

Часто заранее неизвестно, какой уровень зума нужен для отображения объекта целиком.

В этом случае используется метод fitBounds().

map.fitBounds([
    [37.55, 55.70],
    [37.70, 55.80]
]);

MapLibre автоматически подберёт подходящий масштаб.

Дополнительные отступы:

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

Такой способ применяется для отображения:

маршрутов;
полигонов;
групп маркеров;
административных границ.

Получение масштаба во время анимации

Во время плавного приближения можно отслеживать промежуточные значения.

map.on('zoom', () => {
    const zoom = map.getZoom();

    console.log(zoom);
});

Пример вывода:

10.2
10.8
11.4
12.1
12.9
13.0

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

Практический пример управления уровнем зума

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

document.getElementById('city').addEventListener('click', () => {
    map.flyTo({
        center: [37.6176, 55.7558],
        zoom: 12
    });
});

document.getElementById('street').addEventListener('click', () => {
    map.flyTo({
        center: [37.6176, 55.7558],
        zoom: 17
    });
});

map.on('zoomend', () => {
    console.log(
        'Текущий масштаб:',
        map.getZoom().toFixed(2)
    );
});

В данном примере реализованы:

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