setZoom и zoomIn/zoomOut

В библиотеке Leaflet управление масштабом реализовано через набор методов, работающих с уровнем zoom-карты: setZoom, zoomIn и zoomOut. Эти функции являются основой программного контроля приближения и отдаления карты, дополняя интерактивные механизмы (колесо мыши, кнопки масштабирования, жесты на сенсорных устройствах).

setZoom

Метод setZoom устанавливает конкретный уровень масштаба карты.

map.setZoom(zoom, options);

Параметры

  • zoom (Number) — целевой уровень масштабирования. Обычно это целое число, например 0–18, но фактический диапазон зависит от конфигурации тайлового слоя.
  • options (Object) — необязательный объект параметров анимации и поведения.

Поведение

setZoom напрямую задаёт абсолютное значение масштаба. Если переданный уровень выходит за пределы minZoom или maxZoom, он автоматически ограничивается этими значениями.

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

Анимация масштабирования

map.setZoom(12, {
  animate: true
});

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

  • animate (Boolean) — включает плавное изменение масштаба.
  • duration (Number) — длительность анимации в секундах.
  • easeLinearity (Number) — коэффициент плавности интерполяции.

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

Пример использования

const map = L.map('map').setView([51.505, -0.09], 10);

map.setZoom(14);

В этом случае карта сразу переходит на уровень масштабирования 14, сохраняя текущий центр.

zoomIn

Метод zoomIn увеличивает масштаб карты на фиксированное значение шага.

map.zoomIn(delta, options);

Параметры

  • delta (Number) — величина увеличения масштаба. Если не указана, используется значение zoomDelta из настроек карты.
  • options (Object) — параметры анимации.

Механика работы

zoomIn не устанавливает конкретный уровень, а изменяет текущий:

currentZoom + delta

Если итоговое значение превышает maxZoom, оно ограничивается допустимым максимумом.

Пример

map.zoomIn();

map.zoomIn(2, {
  animate: true
});

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

zoomOut

Метод zoomOut выполняет обратное действие — уменьшает уровень масштаба.

map.zoomOut(delta, options);

Параметры

  • delta (Number) — величина уменьшения масштаба.
  • options (Object) — параметры анимации.

Поведение

Фактическое значение рассчитывается как:

currentZoom - delta

Если результат ниже minZoom, применяется ограничение.

Пример использования

map.zoomOut();

map.zoomOut(3, {
  animate: true,
  duration: 0.5
});

Различия между setZoom, zoomIn и zoomOut

Метод Тип изменения Характеристика
setZoom абсолютное фиксирует конкретный уровень
zoomIn относительное увеличивает масштаб
zoomOut относительное уменьшает масштаб

setZoom используется для синхронизации состояния карты с внешними данными, тогда как zoomIn и zoomOut применяются для инкрементального управления.

Ограничения диапазона масштаба

Каждая карта имеет параметры:

  • minZoom
  • maxZoom
L.map('map', {
  minZoom: 5,
  maxZoom: 18
});

При любом изменении масштаба через setZoom, zoomIn или zoomOut значения автоматически нормализуются в пределах заданного диапазона.

Связь с zoomSnap

Параметр zoomSnap влияет на дискретность масштабирования:

L.map('map', {
  zoomSnap: 1
});

При zoomSnap: 1 переходы происходят только по целым уровням. При меньших значениях (например, 0.5) допускаются промежуточные масштабы.

Методы setZoom, zoomIn, zoomOut учитывают это поведение при вычислении итогового значения.

Влияние zoomDelta

zoomDelta определяет шаг изменения при вызове zoomIn() и zoomOut() без параметров:

L.map('map', {
  zoomDelta: 0.5
});

Тогда:

  • zoomIn() → +0.5
  • zoomOut() → −0.5

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

Любое изменение zoom инициирует цепочку событий:

  • zoomstart — начало изменения масштаба
  • zoom — промежуточные изменения при анимации
  • zoomend — завершение изменения

Пример регистрации:

map.on('zoomstart', () => {
  console.log('Начало масштабирования');
});

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

Взаимодействие с setView

Метод setView(latlng, zoom) объединяет установку центра и масштаба:

map.setView([51.505, -0.09], 13);

Фактически внутри происходит вызов логики, эквивалентной:

map.setZoom(13);
map.panTo([51.505, -0.09]);

При этом setZoom остаётся автономным способом изменения только уровня масштаба без изменения центра карты.

Особенности анимации и рендеринга

При изменении zoom:

  1. Пересчитывается проекция координат (CRS).
  2. Обновляется сетка тайлов.
  3. Применяется CSS transform к контейнеру карты.
  4. При необходимости подгружаются новые тайлы с подходящим уровнем детализации.

Плавность зависит от:

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

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

function focusOnArea(map, bounds) {
  map.fitBounds(bounds);
  map.setZoom(map.getZoom() + 1);
}
function resetZoom(map) {
  map.setZoom(10, { animate: true });
}
function zoomStep(map, direction) {
  if (direction === 'in') {
    map.zoomIn();
  } else {
    map.zoomOut();
  }
}

Ограничения и особенности поведения

  • Изменение zoom во время активной анимации может прерывать текущий переход.
  • Частые вызовы setZoom подряд могут приводить к визуальным рывкам.
  • При отключённой анимации переход происходит мгновенно без промежуточных кадров.
  • Значения zoom могут быть дробными при определённых CRS и настройках слоя.
Оглавление