JavaScript Fullscreen API

Introdução à JavaScript Fullscreen API

A JavaScript Fullscreen API permite que uma página web solicite ao navegador que exiba um único elemento — e somente esse elemento — ocupando a tela inteira, ocultando a barra de endereço, as abas e o chrome do sistema operacional. É isso que alimenta o botão de tela cheia que você vê em players de vídeo, jogos online, ferramentas de apresentação e galerias de imagens.

Este capítulo aborda como entrar e sair do modo tela cheia, como reagir às mudanças de estado com eventos, as armadilhas que você encontrará (o requisito de gesto do usuário, a Promise retornada e o estilo), além do suporte a navegadores. Os principais métodos e propriedades são:

• Element.requestFullscreen() — solicita que um elemento ocupe a tela. Retorna uma Promise.
• Document.exitFullscreen() — sai do modo tela cheia e retorna à página normal.
• document.fullscreenElement — o elemento atualmente exibido em tela cheia, ou null se nenhum.
• document.fullscreenEnabled — true se o modo tela cheia estiver disponível e não bloqueado.
• fullscreenchange / fullscreenerror eventos — disparam quando o estado muda ou uma solicitação falha.

Ativando o Modo Tela Cheia em JavaScript

Para entrar em modo tela cheia, chame o método requestFullscreen() em qualquer elemento do DOM que você queira ampliar — um vídeo, uma <div>, um <canvas>, ou até mesmo o document.documentElement inteiro.

Duas regras são importantes desde o início:

1. Um gesto do usuário é obrigatório. Os navegadores só executam requestFullscreen() quando chamado dentro de uma interação real, como um clique ou pressionamento de tecla. Chamá-lo no carregamento da página ou a partir de um temporizador é rejeitado silenciosamente, por isso quase sempre é chamado dentro de um manipulador de eventos.
2. Retorna uma Promise. A Promise é resolvida quando o modo tela cheia é ativado com sucesso e rejeitada (com um erro) se o navegador recusar. Sempre adicione um .catch() para que uma recusa não se torne uma rejeição não tratada.

<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>

Este trecho ativa o modo tela cheia para o elemento video-container quando o botão é clicado. A verificação de document.fullscreenEnabled protege contra navegadores (ou contextos incorporados como um <iframe> em sandbox) onde o recurso está indisponível, e o .catch() registra qualquer recusa em vez de deixá-la falhar silenciosamente.

Controlando a interface de navegação

requestFullscreen() aceita um objeto de opções opcional. A propriedade navigationUI indica se o navegador deve manter seus controles de navegação (botão voltar, barra de URL) visíveis:

// "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" });

É apenas uma dica — o navegador é livre para ignorá-la — mas é útil para jogos e vídeos onde se deseja a visão mais imersiva possível.

Saindo do Modo Tela Cheia

Uma página só pode ter um elemento em tela cheia por vez, portanto não é necessário saber qual elemento está ativo para sair — document.exitFullscreen() sempre sai do atual e retorna a página ao seu layout normal:

<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>

Aqui o usuário sai do modo tela cheia clicando em um botão Exit Fullscreen. A verificação if (document.exitFullscreen) confirma que o método existe antes de chamá-lo. Note que o navegador também permite que o usuário saia a qualquer momento pressionando Esc — seu código não controla isso, e é exatamente por isso que você deve ouvir o evento fullscreenchange em vez de presumir que o seu botão é a única saída.

Tratando Mudanças de Tela Cheia com Eventos

A Fullscreen API dispara eventos sempre que o estado muda, independentemente de como ocorreu — pelo seu botão, pela tecla Esc ou pelo próprio navegador. Ouvi-los é a forma confiável de manter sua interface sincronizada (por exemplo, trocando um ícone de "entrar" por um de "sair"):

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

Este ouvinte de evento registra mensagens no console com base em se o documento está ou não em modo tela cheia, ajudando os desenvolvedores a entender as transições de estado. Além disso, você deve tratar o evento fullscreenerror para capturar casos em que o navegador nega a solicitação (por exemplo, devido a restrições de segurança ou cancelamento pelo usuário):

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

Aqui event.target é o elemento em que a solicitação foi feita; ler .error nele (ou simplesmente registrar o evento) informa por que o navegador recusou.

Agora vamos reunir tudo em um exemplo completo e funcional:

Um Exemplo Completo

<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>

Veja como cada parte funciona:

• O manipulador "Go Fullscreen" verifica document.fullscreenEnabled e então chama element.requestFullscreen() no contêiner de vídeo, capturando qualquer rejeição.
• O manipulador "Exit Fullscreen" chama document.exitFullscreen() para retornar à página normal.
• updateButtonVisibility() exibe o botão de saída somente enquanto um elemento está realmente em tela cheia, lendo document.fullscreenElement.
• O ouvinte fullscreenchange executa updateButtonVisibility() a cada mudança de estado — inclusive quando o usuário pressiona Esc — para que a interface nunca fique fora de sincronia, e o ouvinte fullscreenerror relata uma solicitação recusada.

Compatibilidade e Suporte a Navegadores

A Fullscreen API é suportada em todos os navegadores modernos — Chrome, Firefox, Safari, Opera e Edge — usando os métodos padrão sem prefixo. Versões mais antigas do Safari (e Chrome/Edge muito antigos) usavam o prefixo -webkit- (webkitRequestFullscreen, webkitExitFullscreen). Se precisar suportar esses navegadores, use o nome prefixado como alternativa:

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();
    }
}

Para estilizar um elemento enquanto ele está em tela cheia, use a pseudo-classe CSS :fullscreen:

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

Armadilhas comuns

• Sem gesto do usuário, sem tela cheia. Chamar requestFullscreen() fora de um manipulador de clique ou tecla é rejeitado. Dispare-o a partir de uma interação real.
• iframes em sandbox são bloqueados a menos que o iframe possua o atributo allow="fullscreen".
• Trate a rejeição da Promise. Um usuário pode negar a solicitação, ou uma política pode bloqueá-la — sempre adicione .catch().
• Não confie apenas no seu próprio botão. A tecla Esc sai do modo tela cheia sem tocar no seu código, portanto confie no evento fullscreenchange para atualizar a interface.

Conclusão

A Fullscreen API oferece uma maneira limpa e orientada a gestos de permitir que um único elemento ocupe a tela para vídeo, jogos, apresentações e galerias. Lembre-se dos fundamentos: solicite a partir de um gesto do usuário, trate a Promise retornada, saia com document.exitFullscreen() e mantenha sua interface sincronizada ouvindo o evento fullscreenchange em vez de presumir como o usuário saiu do modo tela cheia.

Para continuar aprendendo, explore eventos do navegador, manipulação do DOM e Promises, todos os quais a Fullscreen API utiliza.

Prática