Элемент: метод requestFullscreen()

Метод Element.requestFullscreen() асинхронно запрашивает переход к полноэкранному режиму для элемента.

Гарантии, что элемент перейдет в полноэкранный режим, нет. Если разрешение на переход в полноэкранный режим предоставлено, возвращённое Promise будет выполнено, и элемент получит событие fullscreenchange, уведомляющее о переходе в полноэкранный режим. Если разрешение отказано, обещание отклонится, и элемент вместо этого получит событие fullscreenerror. Если элемент был отсоединён от исходного документа, эти события будут получены документом.

options Необязательно

Объект, управляющий поведением перехода в полноэкранный режим. Доступные параметры:

navigationUI Необязательно

Определяет, будет ли отображаться навигационное меню в полноэкранном режиме. Значение по умолчанию — "auto", означающее, что браузер решит, как поступить.

"hide"

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

"show"

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

"auto"

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

screen Необязательно Экспериментальное

Указывает, на каком экране вы хотите отобразить элемент в полноэкранном режиме. В качестве значения принимается объект ScreenDetailed, представляющий выбранный экран.

А Promise, которое выполняется со значением undefined при завершении перехода в полноэкранный режим.

Вместо традиционного возбуждения исключения, процедура requestFullscreen() объявляет ошибки, отклоняя Promise . Обработчик отклонения получает одно из следующих значений исключения:

TypeError

Исключение TypeError может быть вызвано в следующих ситуациях:

• Документ, содержащий элемент, не полностью активен; то есть, это не текущий активный документ.
• Элемент не содержится в документе.
• Элементу запрещено использовать функцию fullscreen из-за настроек Политики разрешений или других механизмов контроля доступа.
• Элемент и его документ — это один и тот же узел.
• Элемент — это поповер, который уже отображается через HTMLElement.showPopover().

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

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

• Он должен быть одним из стандартных HTML-элементов или <svg> или <math>.
• Он не должен быть элементом <dialog>.
• Он должен находиться либо в главном документе, либо во <iframe>, которому задан атрибут allowfullscreen.

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

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

Чтобы узнать, когда другой код переключает полноэкранный режим, следует установить обработчики события fullscreenchange на элементе Document. Также важно отслеживать событие fullscreenchange, чтобы, например, отслеживать, когда пользователь вручную включает или выключает полноэкранный режим или когда пользователь переключается между приложениями, что может привести к временной потере полноэкранного режима вашего приложения.

Эта функция переключает первый элемент <video>, найденный в документе, в полноэкранный режим и обратно.

function toggleFullscreen() {
  let elem = document.querySelector("video");

  if (!document.fullscreenElement) {
    elem.requestFullscreen().catch((err) => {
      alert(
        `Error attempting to enable fullscreen mode: ${err.message} (${err.name})`,
      );
    });
  } else {
    document.exitFullscreen();
  }
}

Если документ ещё не находится в полноэкранном режиме (это определяется наличием значения у document.fullscreenElement), мы вызываем метод requestFullscreen() видео. Если запрос был успешен, ничего не требуется; в противном случае, обработчик отклонения обещания выводит сообщение об ошибке.

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

Вы можете посмотреть этот пример в действии или просмотреть или изменить код на Glitch.

В этом примере весь документ переводится в полноэкранный режим путем вызова requestFullscreen() на элементе Document.documentElement, корневом элементе <html> документа.

let elem = document.documentElement;

elem
  .requestFullscreen({ navigationUI: "show" })
  .then(() => {})
  .catch((err) => {
    alert(
      `An error occurred while trying to switch into fullscreen mode: ${err.message} (${err.name})`,
    );
  });

Обработчик выполнения обещания ничего не делает, но если обещание отклонено, отображается сообщение об ошибке с помощью alert().

Если вам необходимо сделать элемент полноэкранным на первичном экране ОС, вы можете использовать следующий код:

try {
  const primaryScreen = (await getScreenDetails()).screens.find(
    (screen) => screen.isPrimary,
  );
  await document.body.requestFullscreen({ screen: primaryScreen });
} catch (err) {
  console.error(err.name, err.message);
}

Метод Window.getScreenDetails() используется для получения объекта ScreenDetails для текущего устройства, содержащего объекты ScreenDetailed, представляющие разные доступные экраны.

• Fullscreen API
• Document.exitFullscreen()
• Document.fullscreen
• Document.fullscreenElement
• :fullscreen
• allowfullscreen