JavaScript Fullscreen API

Введение в JavaScript Fullscreen API

JavaScript Fullscreen API позволяет веб-странице попросить браузер отобразить один элемент — и только его — на всём экране, скрыв адресную строку, вкладки и системный интерфейс операционной системы. Именно это обеспечивает работу кнопки полноэкранного режима в видеоплеерах, онлайн-играх, инструментах для презентаций и галереях изображений.

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

• Element.requestFullscreen() — запрашивает отображение элемента на весь экран. Возвращает Promise.
• Document.exitFullscreen() — выходит из полноэкранного режима и возвращает обычный вид страницы.
• document.fullscreenElement — элемент, отображаемый в данный момент в полноэкранном режиме, или null, если такого нет.
• document.fullscreenEnabled — true, если полноэкранный режим доступен и не заблокирован.
• fullscreenchange / fullscreenerror — события, возникающие при изменении состояния или при неудачном запросе.

Включение полноэкранного режима в JavaScript

Чтобы войти в полноэкранный режим, вызовите метод requestFullscreen() на любом элементе DOM, который нужно развернуть — видео, <div>, <canvas> или даже document.documentElement целиком.

С самого начала важны два правила:

1. Требуется пользовательский жест. Браузеры выполняют requestFullscreen() только тогда, когда вызов происходит внутри реального взаимодействия — клика или нажатия клавиши. Вызов при загрузке страницы или из таймера молча отклоняется, поэтому метод почти всегда вызывается внутри обработчика событий.
2. Метод возвращает Promise. Promise разрешается при успешном переходе в полноэкранный режим и отклоняется (с ошибкой), если браузер отказывает. Всегда добавляйте .catch(), чтобы отказ не стал необработанным исключением.

<div id="main-content">
    <button id="fs-btn">Go Fullscreen</button>
    <div id="video-container">
        <!-- Your content like a video or interactive media -->
    </div>
</div>

<script>
const element = document.getElementById("video-container");
const btn = document.getElementById("fs-btn");

btn.addEventListener("click", function() {
    if (document.fullscreenEnabled) {
        element.requestFullscreen().catch(err => {
            console.error(`Error attempting to enable fullscreen: ${err.message}`);
        });
    } else {
        console.log("Fullscreen API is not supported in this browser.");
    }
});
</script>

Этот фрагмент активирует полноэкранный режим для элемента video-container по клику на кнопку. Проверка document.fullscreenEnabled защищает от браузеров (или встроенных контекстов, например песочницы <iframe>), где функция недоступна, а .catch() сообщает о любом отказе вместо того, чтобы он прошёл незамеченным.

Управление навигационным интерфейсом

requestFullscreen() принимает необязательный объект с параметрами. Свойство navigationUI подсказывает браузеру, следует ли оставлять видимыми элементы навигации (кнопку «Назад», адресную строку):

// "hide"  → request a truly immersive, chrome-free view (default for most browsers)
// "show"  → keep the browser's navigation UI on screen
// "auto"  → let the browser decide
element.requestFullscreen({ navigationUI: "hide" });

Это лишь подсказка — браузер вправе её проигнорировать, — но она полезна для игр и видео, где нужна максимальная иммерсивность.

Выход из полноэкранного режима

На странице может быть только один полноэкранный элемент одновременно, поэтому знать, какой именно элемент активен, не нужно — document.exitFullscreen() всегда завершает текущий полноэкранный режим и возвращает страницу в обычный вид:

<div id="exit-button">
    <button id="exit-btn">Exit Fullscreen</button>
</div>

<script>
document.getElementById("exit-btn").addEventListener("click", function() {
    if (document.exitFullscreen) {
        document.exitFullscreen();
    }
});
</script>

Здесь пользователь выходит из полноэкранного режима по клику на кнопку Exit Fullscreen. Проверка if (document.exitFullscreen) подтверждает наличие метода перед его вызовом. Обратите внимание: браузер также позволяет пользователю выйти в любой момент, нажав Esc — ваш код не управляет этим, именно поэтому следует слушать событие fullscreenchange, а не предполагать, что ваша кнопка — единственный способ выйти.

Обработка изменений полноэкранного режима с помощью событий

Fullscreen API генерирует события при каждом изменении состояния, независимо от причины — ваша кнопка, клавиша Esc или сам браузер. Прослушивание этих событий — надёжный способ синхронизировать интерфейс (например, менять иконку «войти» на «выйти»):

document.addEventListener("fullscreenchange", function(event) {
    if (document.fullscreenElement) {
        console.log("Entered fullscreen mode");
    } else {
        console.log("Exited fullscreen mode");
    }
});

Этот обработчик выводит сообщения в консоль в зависимости от того, находится ли документ в полноэкранном режиме, помогая разработчикам отслеживать переходы состояний. Кроме того, стоит обрабатывать событие fullscreenerror, чтобы перехватывать случаи, когда браузер отказывает в запросе (например, из-за ограничений безопасности или отмены пользователем):

document.addEventListener("fullscreenerror", function(event) {
    console.error("Fullscreen request failed:", event.target.error);
});

Здесь event.target — элемент, для которого был сделан запрос; чтение .error на нём (или просто вывод события) показывает, почему браузер отказал.

Теперь соберём всё вместе в полном рабочем примере:

Полный пример

<div id="main-content">
    <button id="fs-btn">Go Fullscreen</button>
    <div id="video-container" style="position: relative; height: 100vh; display: flex; align-items: center; justify-content: center;">
        <div id="exit-button" style="display: none;">
            <button id="exit-btn">Exit Fullscreen</button>
        </div>
    </div>
</div>

<script>
const element = document.getElementById("video-container");
const exitBtn = document.getElementById("exit-btn");
const exitButtonContainer = document.getElementById("exit-button");

document.getElementById("fs-btn").addEventListener("click", function() {
    if (document.fullscreenEnabled) {
        element.requestFullscreen().catch(err => {
            console.error(`Error attempting to enable fullscreen: ${err.message}`);
        });
    }
});

exitBtn.addEventListener("click", function() {
    if (document.exitFullscreen) {
        document.exitFullscreen();
    }
});

function updateButtonVisibility() {
    exitButtonContainer.style.display = document.fullscreenElement ? "block" : "none";
}

document.addEventListener("fullscreenchange", updateButtonVisibility);
document.addEventListener("fullscreenerror", function(event) {
    console.error("Fullscreen request failed:", event.target.error);
});
</script>

Вот как работает каждая часть:

• Обработчик «Go Fullscreen» проверяет document.fullscreenEnabled и затем вызывает element.requestFullscreen() для контейнера видео, перехватывая любой отказ.
• Обработчик «Exit Fullscreen» вызывает document.exitFullscreen() для возврата к обычному виду страницы.
• updateButtonVisibility() показывает кнопку выхода только тогда, когда какой-либо элемент действительно находится в полноэкранном режиме, читая document.fullscreenElement.
• Слушатель fullscreenchange запускает updateButtonVisibility() при каждом изменении состояния — в том числе когда пользователь нажимает Esc — чтобы интерфейс никогда не рассинхронизировался; слушатель fullscreenerror сообщает об отклонённом запросе.

Совместимость и поддержка браузерами

Fullscreen API поддерживается всеми современными браузерами — Chrome, Firefox, Safari, Opera и Edge — с использованием стандартных методов без префиксов. Более старый Safari (а также очень старые Chrome/Edge) использовали префикс -webkit- (webkitRequestFullscreen, webkitExitFullscreen). Если вам нужна поддержка этих браузеров, используйте имена с префиксом в качестве запасного варианта:

function openFullscreen(element) {
    if (element.requestFullscreen) {
        return element.requestFullscreen();
    }
    if (element.webkitRequestFullscreen) { // older Safari
        return element.webkitRequestFullscreen();
    }
}

function closeFullscreen() {
    if (document.exitFullscreen) {
        return document.exitFullscreen();
    }
    if (document.webkitExitFullscreen) { // older Safari
        return document.webkitExitFullscreen();
    }
}

Для стилизации элемента в полноэкранном режиме используйте псевдокласс CSS :fullscreen:

#video-container:fullscreen {
    background-color: #000;
    color: #fff;
    padding: 20px;
}

Типичные подводные камни

• Без пользовательского жеста — нет полноэкранного режима. Вызов requestFullscreen() вне обработчика клика или нажатия клавиши будет отклонён. Запускайте его только из реального взаимодействия.
• Песочница <iframe> заблокирует запрос, если у элемента <iframe> нет атрибута allow="fullscreen".
• Обрабатывайте отклонение Promise. Пользователь может отказать в запросе, или его может заблокировать политика — всегда добавляйте .catch().
• Не полагайтесь только на свою кнопку. Клавиша Esc выходит из полноэкранного режима, не затрагивая ваш код, поэтому для обновления интерфейса опирайтесь на событие fullscreenchange.

Заключение

Fullscreen API предоставляет чистый, управляемый жестами способ развернуть отдельный элемент на весь экран для видео, игр, презентаций и галерей. Запомните главное: запрашивайте полноэкранный режим из пользовательского жеста, обрабатывайте возвращаемый Promise, выходите через document.exitFullscreen() и синхронизируйте интерфейс, слушая событие fullscreenchange, а не предполагая, как именно пользователь вышел из полноэкранного режима.

Для дальнейшего изучения исследуйте события браузера, работу с DOM и Promise — всё это лежит в основе Fullscreen API.

Практика