FullscreenControl

FullscreenControl — встроенный элемент управления в MapLibre GL JS, предназначенный для переключения карты в полноэкранный режим и обратно. Он является частью стандартного набора контролов карты и опирается на Fullscreen API браузера, обеспечивая расширенный визуальный режим отображения карты без интерфейсных ограничений страницы.

FullscreenControl отвечает за управление состоянием отображения контейнера карты. При активации контрол изменяет режим отображения DOM-элемента, в котором инициализирована карта, переводя его в полноэкранный режим, если браузер поддерживает соответствующий API.

Ключевая особенность заключается в том, что контроль не изменяет саму карту как объект — он работает исключительно с контейнером, в который карта встроена. Это означает, что все стили, источники данных и слои остаются неизменными, меняется только контекст отображения.

Поведение контролла можно описать как переключатель состояния:

  • обычный режим отображения (в пределах блока страницы)
  • полноэкранный режим (занимает весь экран пользователя)

Инициализация и подключение

FullscreenControl добавляется к экземпляру карты через метод addControl. Базовая схема выглядит следующим образом:

import maplibregl from "maplibre-gl";

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

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

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

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

Опции конструктора

FullscreenControl поддерживает набор опций, позволяющих адаптировать его поведение под особенности конкретного приложения.

container

Основная опция — container. Она задаёт DOM-элемент, который будет переводиться в полноэкранный режим.

map.addControl(new maplibregl.FullscreenControl({
  container: document.getElementById("map-wrapper")
}));

Если параметр не указан, используется контейнер карты по умолчанию.

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

Внутренний механизм работы

FullscreenControl использует Fullscreen API браузера, который включает следующие методы:

  • requestFullscreen()
  • exitFullscreen()
  • события изменения состояния полноэкранного режима

Контрол отслеживает текущее состояние и переключает его при нажатии кнопки.

Логика работы строится на проверке:

  • находится ли документ в fullscreen
  • какой элемент сейчас является fullscreen-элементом
  • поддерживается ли API в текущем браузере

Если API недоступен, кнопка может быть скрыта или неактивна.

Состояния и переключение режима

FullscreenControl управляет состояниями через toggle-механику:

  1. Проверка текущего состояния документа
  2. Если fullscreen не активен — вызов requestFullscreen на контейнере
  3. Если fullscreen активен — вызов exitFullscreen

При этом важно учитывать, что разные браузеры исторически использовали префиксы (webkit, moz), однако современные версии MapLibre GL JS абстрагируют эти различия.

Взаимодействие с другими контролами

FullscreenControl часто используется совместно с другими элементами управления картой:

  • ZoomControl (приближение/отдаление)
  • NavigationControl (комплексный набор навигации)
  • AttributionControl (информация об источниках данных)

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

Особое внимание следует уделять расположению интерфейсных элементов, поскольку fullscreen может изменять визуальные приоритеты слоёв и перекрытий.

Стилизация и внешний вид

Визуально FullscreenControl представляет собой кнопку с иконкой переключения режима. Стили задаются через стандартные CSS-классы MapLibre:

  • .maplibregl-ctrl
  • .maplibregl-ctrl-fullscreen

Изменение внешнего вида возможно через переопределение CSS:

.maplibregl-ctrl-fullscreen {
  background-color: #ffffff;
  border-radius: 4px;
}

Также возможно полное скрытие контролла, если управление fullscreen реализуется через собственный UI:

.maplibregl-ctrl-fullscreen {
  display: none;
}

Программное управление fullscreen

Хотя FullscreenControl предоставляет пользовательский интерфейс, разработчики могут управлять полноэкранным режимом напрямую через API браузера.

Пример:

const container = map.getContainer();

function enterFullscreen() {
  if (container.requestFullscreen) {
    container.requestFullscreen();
  }
}

function exitFullscreen() {
  if (document.exitFullscreen) {
    document.exitFullscreen();
  }
}

В таких сценариях FullscreenControl может быть либо отключён, либо использоваться как дополнительный способ взаимодействия.

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

Работа fullscreen режима зависит от ряда факторов:

  • необходимость пользовательского действия (например, клик)
  • ограничения мобильных браузеров
  • различия в реализации Fullscreen API

На мобильных устройствах поведение может отличаться: некоторые браузеры открывают карту в псевдо-fullscreen режиме, скрывая адресную строку без реального перехода в fullscreen.

Также важно учитывать, что переход в fullscreen может влиять на:

  • обработку событий resize
  • пересчёт размеров карты
  • перерисовку тайлов

MapLibre автоматически обрабатывает изменение размера контейнера, но в сложных интерфейсах иногда требуется ручной вызов:

map.resize();

Работа с событиями fullscreen

Контрол и карта могут реагировать на события изменения состояния fullscreen:

document.addEventListener("fullscreenchange", () => {
  console.log("Состояние fullscreen изменилось");
});

Это позволяет синхронизировать интерфейс приложения с режимом отображения, например:

  • скрывать боковые панели
  • менять расположение UI-элементов
  • изменять размеры вспомогательных компонентов

Использование в кастомных интерфейсах

FullscreenControl часто заменяется кастомными кнопками в приложениях с собственным UI. В таких случаях логика остаётся аналогичной:

  • проверка состояния fullscreen
  • вызов requestFullscreen / exitFullscreen
  • обработка события fullscreenchange

Интеграция с картой при этом остаётся минимальной, так как FullscreenControl не зависит от других компонентов MapLibre и не требует дополнительных слоёв конфигурации.

Поведение при повторной инициализации карты

При уничтожении и повторном создании карты FullscreenControl не сохраняет состояния. Каждый новый экземпляр карты требует повторного добавления контролла.

Это важно учитывать в SPA-приложениях, где карта может пересоздаваться при смене маршрутов или контекста отображения.

Взаимодействие с размерами и перерисовкой

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

MapLibre GL JS автоматически вызывает перерасчёт viewport, однако в нестандартных сценариях может потребоваться принудительное обновление:

map.once("resize", () => {
  map.repaint = true;
});

FullscreenControl в этом процессе выступает лишь триггером изменения DOM-структуры, не участвуя в рендеринге напрямую.

Практическое применение в интерфейсах карт

FullscreenControl особенно полезен в следующих сценариях:

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

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

Оглавление