API полноэкранного режима

API полноэкранного режима добавляет методы для отображения определённого Element (и его потомков) в полноэкранном режиме и для выхода из полноэкранного режима, когда он больше не нужен. Это позволяет отображать желаемое содержимое, например, онлайн-игру, на весь экран пользователя, скрывая все элементы пользовательского интерфейса браузера и другие приложения до тех пор, пока полноэкранный режим не будет отключен.

Подробную информацию о том, как использовать API, см. в статье Руководство по API полноэкранного режима.

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

API полноэкранного режима добавляет методы к интерфейсам Document и Element для включения и выключения полноэкранного режима.

Document.exitFullscreen()

Запрашивает у пользователя агента переход из полноэкранного режима обратно в оконный режим. Возвращает Promise, который разрешается, когда полноэкранный режим будет полностью отключен.

Element.requestFullscreen()

Запрашивает у пользователя агента переход к указанному элементу (и, по аналогии, его потомкам) в полноэкранный режим, скрывая все элементы пользовательского интерфейса браузера, а также все другие приложения на экране. Возвращает Promise, который разрешается, когда полноэкранный режим будет активирован.

Document.fullscreenElement / ShadowRoot.fullscreenElement

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

Document.fullscreenEnabled

Свойство fullscreenEnabled указывает, разрешен ли полноэкранный режим. Оно false в случае невозможности включения полноэкранного режима (например, если функция "fullscreen" не разрешена или полноэкранный режим не поддерживается).

Document.fullscreen Устаревшее

Булево значение, которое true если в документе есть элемент, который в данный момент отображается в полноэкранном режиме; в противном случае возвращает false.

Примечание: Используйте свойство fullscreenElement для интерфейса Document или ShadowRoot; если оно не null, значит, это Element, который в данный момент отображается в полноэкранном режиме.

fullscreenchange

Отправляется элементу Element при переходе в полноэкранный режим или выходе из него.

fullscreenerror

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

Доступ к полноэкранному режиму можно контролировать с помощью Политики разрешений. Функция полноэкранного режима идентифицируется строкой "fullscreen", а значение по умолчанию списка разрешений — "self", что означает разрешение полноэкранного режима в контекстах верхнего уровня документов, а также для вложенных контекстов просмотра, загруженных из того же источника, что и документ верхнего уровня.

Пользователи могут выбрать выход из полноэкранного режима, нажав клавишу ESC (или F11), вместо ожидания программного выхода сайта или приложения. Убедитесь, что в пользовательском интерфейсе есть соответствующие элементы управления, информирующие пользователя об этом варианте.

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

Просмотреть живой пример

Отслеживание нажатия клавиши 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. В реальной реализации на этом этапе следует проверить префиксные версии (mozFullScreenElement, msFullscreenElement, или webkitFullscreenElement, например). Если значение равно null, документ находится в оконном режиме, поэтому необходимо переключиться в полноэкранный режим; в противном случае это элемент, который в данный момент находится в полноэкранном режиме. Переключение в полноэкранный режим выполняется путем вызова Element.requestFullscreen() для элемента <video>.

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

• Element.requestFullscreen()
• Document.exitFullscreen()
• Document.fullscreen
• Document.fullscreenElement
• :fullscreen, ::backdrop
• allowfullscreen