Руководство по API полноэкранного режима

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

Для перевода элемента (например, <video>) в полноэкранный режим, можно вызвать его метод requestFullscreen().

Рассмотрим этот элемент <video>:

<video controls id="my-video">
  <source src="somevideo.webm" />
  <source src="somevideo.mp4" />
</video>

Мы можем перевести это видео в полноэкранный режим следующим образом:

const elem = document.getElementById("my-video");
if (elem.requestFullscreen) {
  elem.requestFullscreen();
}

Этот код проверяет наличие метода requestFullscreen() перед его вызовом.

При успешном переходе в полноэкранный режим документ, содержащий элемент, получает событие fullscreenchange. При выходе из полноэкранного режима документ снова получает событие fullscreenchange. Обратите внимание, что событие fullscreenchange само по себе не содержит информации о переходе в или из полноэкранного режима, но если у документа есть ненулевой элемент fullscreenElement, значит вы находитесь в полноэкранном режиме.

Не гарантируется, что переход в полноэкранный режим всегда будет успешным. Например, элементы <iframe> требуют атрибута allowfullscreen, чтобы разрешить отображение их содержимого в полноэкранном режиме. Кроме того, некоторые виды контента, такие как оконные плагины, не могут быть представлены в полноэкранном режиме. Попытка перевести элемент, который не может отображаться в полноэкранном режиме (или его родитель или дочерний элемент), не сработает. Вместо этого, элемент, запросивший полноэкранный режим, получит событие fullscreenerror. Если запрос на полноэкранный режим не удался, Firefox запишет сообщение об ошибке в консоль браузера, объясняя причину неудачи. В Chrome и более новых версиях Opera такого предупреждения не генерируется.

Пользователь всегда может выйти из полноэкранного режима; см. Рекомендации для пользователей. Вы также можете сделать это программно, вызвав метод Document.exitFullscreen().

Объект Document предоставляет дополнительную информацию, которая может быть полезна при разработке полноэкранных веб-приложений:

Document.fullscreenElement / ShadowRoot.fullscreenElement

Свойство fullscreenElement указывает на элемент Element, который в настоящее время отображается в полноэкранном режиме. Если это ненулевой элемент, документ (или теневой DOM) находится в полноэкранном режиме. Если это null, документ (или теневой DOM) не находится в полноэкранном режиме.

Document.fullscreenEnabled

Свойство fullscreenEnabled указывает, разрешен ли в данный момент полноэкранный режим для документа.

Некоторые мобильные браузеры в полноэкранном режиме игнорируют настройки мета-тега viewport и блокируют масштабирование пользователем; например, жест «приближение-отдаление» может не работать на странице в полноэкранном режиме, даже если в обычном режиме страница может масштабироваться с помощью этого же жеста.

Необходимо проинформировать пользователей о том, что они могут нажать клавишу Esc (или F11), чтобы выйти из полноэкранного режима.

Кроме того, переход на другую страницу, смену вкладок или переключение на другое приложение (например, с помощью Alt-Tab) также приводит к выходу из полноэкранного режима.

В этом примере видео отображается на веб-странице. Нажатие клавиши Return или Enter позволяет пользователю переключаться между оконным и полноэкранным режимами отображения видео.

Посмотреть примеры

После загрузки страницы выполняется этот код для установки обработчика события, отслеживающего нажатие клавиши Enter.

document.addEventListener(
  "keydown",
  (e) => {
    if (e.key === "Enter") {
      toggleFullScreen();
    }
  },
  false,
);

Этот код вызывается при нажатии пользователем клавиши Enter, как показано выше.

function toggleFullScreen() {
  if (!document.fullscreenElement) {
    document.documentElement.requestFullscreen();
  } else if (document.exitFullscreen) {
    document.exitFullscreen();
  }
}

Код начинает с проверки значения атрибута fullscreenElement у элемента document. Если оно null, значит документ в данный момент в оконном режиме, и нам нужно переключиться в полноэкранный режим. Переключение в полноэкранный режим осуществляется вызовом Element.requestFullscreen().

Если полноэкранный режим уже активен (fullscreenElement не равно null), мы вызываем document.exitFullscreen().

• Использование полноэкранного режима
• Element.requestFullscreen()
• Document.exitFullscreen()
• Document.fullscreen
• Document.fullscreenElement
• :fullscreen, ::backdrop
• allowfullscreen