Leaflet.fullscreen

Плагин fullscreen для Leaflet добавляет возможность разворачивать карту на весь экран браузера с использованием стандартизированного Fullscreen API. Он интегрируется как расширение слоя карты и не требует изменения базовой архитектуры приложения.

Основная задача расширения — управление режимом отображения карты в полноэкранном режиме с сохранением всех интерактивных возможностей: зумирования, панорамирования, работы слоёв и обработчиков событий.

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

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

Подключение через CDN

Плагин подключается после основной библиотеки Leaflet:

<link rel="stylesheet" href="https://unpkg.com/leaflet/dist/leaflet.css" />

<script src="https://unpkg.com/leaflet/dist/leaflet.js"></script>
<script src="https://unpkg.com/leaflet.fullscreen/Control.FullScreen.js"></script>
<link rel="stylesheet" href="https://unpkg.com/leaflet.fullscreen/Control.FullScreen.css" />

Установка через npm

npm install leaflet.fullscreen

Подключение в модульной системе:

import L from 'leaflet';
import 'leaflet.fullscreen';
import 'leaflet.fullscreen/Control.FullScreen.css';

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

После подключения плагина в объект карты добавляется контрол:

const map = L.map('map', {
    fullscreenControl: true
}).setView([51.505, -0.09], 13);

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

Конфигурация параметров

Плагин поддерживает набор опций, передаваемых в инициализации карты.

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

const map = L.map('map', {
    fullscreenControl: true,
    fullscreenControlOptions: {
        position: 'topleft',
        title: {
            'false': 'Открыть полноэкранный режим',
            'true': 'Выйти из полноэкранного режима'
        }
    }
});

Параметры fullscreenControlOptions

  • position — позиция кнопки на карте (topleft, topright, bottomleft, bottomright)
  • title — текст подсказки в зависимости от состояния
  • forceSeparateButton — создание отдельной кнопки вместо объединения с другими контролами (зависит от версии плагина)

API управления полноэкранным режимом

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

Включение режима

map.toggleFullscreen();

Метод переключает текущее состояние: если карта не в fullscreen, активирует его, иначе выключает.

Принудительное включение и выключение

Некоторые версии плагина предоставляют прямые методы:

map.enterFullscreen();
map.exitFullscreen();

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

Состояния карты

Карты могут находиться в двух основных состояниях:

  • обычный режим отображения
  • полноэкранный режим

Состояние можно проверить:

map.isFullscreen();

Метод возвращает true или false.

События fullscreen

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

fullscreenchange

Основное событие изменения состояния:

map.on('fullscreenchange', function () {
    console.log(map.isFullscreen());
});

fullscreenerror

Срабатывает при невозможности перейти в полноэкранный режим:

map.on('fullscreenerror', function () {
    console.log('Ошибка перехода в fullscreen');
});

Особенности реализации Fullscreen API

Плагин опирается на нативный Fullscreen API браузера:

  • requestFullscreen
  • exitFullscreen
  • события fullscreenchange и fullscreenerror

В разных браузерах используются префиксы:

  • webkitRequestFullscreen
  • mozRequestFullScreen
  • msRequestFullscreen

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

Поведение карты в полноэкранном режиме

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

  • пересчитываются тайлы
  • обновляется viewport
  • корректируется центр карты
  • сохраняются уровни zoom

Для ручного обновления используется:

map.invalidateSize();

Этот метод критичен при изменении контейнера вне стандартных событий.

Интеграция с другими контролами

Fullscreen-контрол может конфликтовать с другими UI-элементами, размещёнными в той же позиции. Для предотвращения перекрытия применяется:

fullscreenControlOptions: {
    position: 'topright'
}

Также возможно комбинирование с контролами слоёв и масштабирования:

L.control.layers(baseLayers, overlays).addTo(map);
L.control.zoom({ position: 'bottomright' }).addTo(map);

Программное управление через DOM

Fullscreen может быть вызван не только через API плагина, но и через DOM-элементы:

document.querySelector('.leaflet-control-fullscreen-button').click();

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

Ограничения браузеров

Поведение fullscreen зависит от политики браузера:

  • переход возможен только по пользовательскому действию (клик, клавиша)
  • iframe может блокировать fullscreen без разрешений
  • мобильные браузеры ограничивают автозапуск

На уровне API это приводит к срабатыванию fullscreenerror.

Использование в SPA-приложениях

В одностраничных приложениях fullscreen состояние должно учитываться при:

  • размонтировании компонента карты
  • переходах между маршрутами
  • изменении размеров контейнера

Пример сброса состояния:

if (map.isFullscreen()) {
    map.exitFullscreen();
}

Стилизация кнопки fullscreen

CSS плагина может быть переопределён для адаптации под дизайн интерфейса:

.leaflet-control-fullscreen-button {
    background-color: #fff;
    border-radius: 4px;
}

Также используются псевдоклассы состояния:

.leaflet-fullscreen-on .leaflet-control-fullscreen-button {
    background-color: #f0f0f0;
}

Работа в связке с адаптивной версткой

Fullscreen влияет на размеры контейнера карты, поэтому важно учитывать:

  • height: 100% для родительских блоков
  • отсутствие фиксированных ограничений по высоте
  • корректное поведение flex/grid контейнеров

Карты на Leaflet в fullscreen режиме требуют стабильной геометрии контейнера для корректного рендеринга тайлов.

Обработка переходов и восстановление состояния

При выходе из fullscreen полезно восстанавливать параметры интерфейса:

map.on('fullscreenchange', function () {
    if (!map.isFullscreen()) {
        map.setZoom(map.getZoom());
    }
});

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

Оглавление