JumpTo для мгновенных переходов

Метод jumpTo() в MapLibre GL JS предназначен для мгновенного изменения состояния карты без анимации. В отличие от методов easeTo() и flyTo(), которые плавно перемещают карту между двумя состояниями, jumpTo() выполняет переход немедленно: центр карты, масштаб, поворот и наклон изменяются за один кадр.

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

Общий синтаксис:

map.jumpTo(options);

Параметр options представляет собой объект с настройками нового состояния карты.

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

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

Изменение центра карты

Для мгновенного перемещения используется параметр center.

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

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

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

Параметр zoom задаёт новый уровень масштабирования.

map.jumpTo({
    zoom: 12
});

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

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

Наиболее распространённый вариант использования:

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

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

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

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

map.jumpTo({
    bearing: 90
});

После выполнения север окажется справа.

Значения задаются в градусах:

Значение	Направление
0	Север сверху
90	Север справа
180	Север снизу
270	Север слева

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

Параметр pitch определяет угол наклона камеры.

map.jumpTo({
    pitch: 60
});

Чем больше значение, тем сильнее выражен псевдо-3D эффект.

Полное изменение состояния карты

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

map.jumpTo({
    center: [37.6176, 55.7558],
    zoom: 14,
    bearing: 45,
    pitch: 60
});

Карта мгновенно перейдёт к новому состоянию.

Структура объекта настроек

Объект options может содержать следующие свойства:

{
    center: [lng, lat],
    zoom: Number,
    bearing: Number,
    pitch: Number
}

Пример:

map.jumpTo({
    center: [30.3141, 59.9386],
    zoom: 13,
    bearing: 120,
    pitch: 45
});

Отличия от `easeTo()`

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

Использование `jumpTo()`

map.jumpTo({
    center: [30.3141, 59.9386],
    zoom: 12
});

Результат:

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

Использование `easeTo()`

map.easeTo({
    center: [30.3141, 59.9386],
    zoom: 12,
    duration: 3000
});

Результат:

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

Сравнение

Характеристика	jumpTo	easeTo
Анимация	Нет	Да
Скорость перехода	Мгновенно	Постепенно
Нагрузка на рендеринг	Минимальная	Выше
Подходит для служебных операций	Да	Не всегда
Подходит для красивых переходов	Нет	Да

Отличия от `flyTo()`

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

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

Во время выполнения происходит:

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

Аналогичный вызов через jumpTo():

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

Выполнится моментально без каких-либо визуальных эффектов.

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

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

map.on('load', () => {
    map.jumpTo({
        center: [37.6176, 55.7558],
        zoom: 11
    });
});

Такой подход гарантирует, что объект карты уже готов к изменениям.

Перемещение к объекту после выбора

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

cityList.addEventListener('change', (event) => {
    const city = cities[event.target.value];

    map.jumpTo({
        center: city.coordinates,
        zoom: 13
    });
});

Пример структуры данных:

const cities = {
    moscow: {
        coordinates: [37.6176, 55.7558]
    },
    spb: {
        coordinates: [30.3141, 59.9386]
    }
};

Работа с результатами поиска

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

function showLocation(result) {
    map.jumpTo({
        center: result.center,
        zoom: 15
    });
}

Такой сценарий часто используется во внутренних корпоративных системах и панелях мониторинга.

Быстрое переключение между регионами

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

const regions = {
    europe: {
        center: [15, 50],
        zoom: 4
    },
    asia: {
        center: [100, 35],
        zoom: 3
    },
    america: {
        center: [-100, 40],
        zoom: 3
    }
};

function switchRegion(name) {
    map.jumpTo(regions[name]);
}

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

Использование в системах мониторинга

В диспетчерских интерфейсах важна скорость отображения информации.

Например, при выборе транспортного средства:

function focusVehicle(vehicle) {
    map.jumpTo({
        center: vehicle.position,
        zoom: 16
    });
}

Каждый новый объект отображается немедленно.

Синхронизация нескольких карт

Иногда требуется отображать одну и ту же область на нескольких экземплярах карты.

mainMap.on('move', () => {
    secondMap.jumpTo({
        center: mainMap.getCenter(),
        zoom: mainMap.getZoom(),
        bearing: mainMap.getBearing(),
        pitch: mainMap.getPitch()
    });
});

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

Получение текущего состояния и последующий переход

Текущее состояние карты можно сохранить и затем восстановить.

Сохранение

const state = {
    center: map.getCenter(),
    zoom: map.getZoom(),
    bearing: map.getBearing(),
    pitch: map.getPitch()
};

Восстановление

map.jumpTo(state);

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

Обработка событий при использовании `jumpTo()`

Несмотря на отсутствие анимации, события карты продолжают генерироваться.

Пример:

map.on('move', () => {
    console.log('Карта перемещена');
});

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

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

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

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

map.setMaxBounds([
    [30, 50],
    [40, 60]
]);

map.jumpTo({
    center: [100, 80]
});

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

Работа с пользовательскими кнопками

Создание кнопки быстрого перехода:

document
    .getElementById('homeButton')
    .addEventListener('click', () => {
        map.jumpTo({
            center: [37.6176, 55.7558],
            zoom: 10,
            bearing: 0,
            pitch: 0
        });
    });

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

Переход к координатам из API

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

fetch('/api/location')
    .then(response => response.json())
    .then(location => {
        map.jumpTo({
            center: location.coordinates,
            zoom: 14
        });
    });

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

Производительность и особенности использования

Метод jumpTo() считается наиболее лёгким способом изменения положения камеры, поскольку:

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

Особенно заметны преимущества при:

мониторинге транспорта;
отображении телеметрии;
обновлении положения объектов в реальном времени;
синхронизации нескольких карт;
восстановлении сохранённого состояния интерфейса.

Типичные ошибки

Передача широты и долготы в неправильном порядке

Неверно:

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

В MapLibre используется порядок:

[lng, lat]

Правильно:

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

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

Неверно:

map.jumpTo({
    zoom: 10
});

если объект map ещё не создан.

Корректный вариант:

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

map.on('load', () => {
    map.jumpTo({
        zoom: 10
    });
});

Ожидание плавной анимации

Некорректное предположение:

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

не создаёт перехода между точками.

Для анимированного перемещения необходимо использовать:

map.easeTo(...)

или

map.flyTo(...)

Практические сценарии применения

Быстрое восстановление сохранённого вида

map.jumpTo(savedView);

Переход к выбранному объекту

map.jumpTo({
    center: markerCoordinates,
    zoom: 16
});

Синхронизация обзорной карты

overviewMap.jumpTo({
    center: mainMap.getCenter(),
    zoom: mainMap.getZoom()
});

Обновление положения отслеживаемого объекта

map.jumpTo({
    center: vehiclePosition
});

Сброс ориентации карты

map.jumpTo({
    bearing: 0,
    pitch: 0
});

Метод jumpTo() представляет собой базовый механизм мгновенного изменения камеры в MapLibre GL JS и используется во всех сценариях, где важны скорость реакции интерфейса, точность синхронизации и отсутствие анимационных переходов.