JavaScript Fullscreen API

Introduzione alla JavaScript Fullscreen API

La JavaScript Fullscreen API consente a una pagina web di chiedere al browser di mostrare un singolo elemento — e solo quell'elemento — utilizzando l'intero schermo, nascondendo la barra degli indirizzi, le schede e il chrome del sistema operativo. È ciò che alimenta il pulsante a schermo intero che vedi nei lettori video, nei giochi online, negli strumenti di presentazione e nelle gallerie di immagini.

Questo capitolo spiega come entrare ed uscire dalla modalità a schermo intero, come reagire ai cambiamenti di stato tramite eventi, le insidie che incontrerai (il requisito del gesto utente, la Promise restituita e la gestione degli stili) e il supporto dei browser. I metodi e le proprietà principali sono:

• Element.requestFullscreen() — richiede che un elemento occupi l'intero schermo. Restituisce una Promise.
• Document.exitFullscreen() — esce dalla modalità a schermo intero e ripristina la normale visualizzazione della pagina.
• document.fullscreenElement — l'elemento attualmente mostrato a schermo intero, oppure null se non ce n'è nessuno.
• document.fullscreenEnabled — true se la modalità a schermo intero è disponibile e non bloccata.
• fullscreenchange / fullscreenerror eventi — si attivano quando lo stato cambia o una richiesta fallisce.

Attivare la Modalità a Schermo Intero in JavaScript

Per entrare in modalità a schermo intero, chiama il metodo requestFullscreen() su qualsiasi elemento DOM che vuoi ingrandire — un video, un <div>, un <canvas>, persino l'intero document.documentElement.

Due regole sono fondamentali fin dall'inizio:

1. È richiesto un gesto utente. I browser eseguono requestFullscreen() solo quando è chiamato all'interno di una vera interazione, come un clic o la pressione di un tasto. Chiamarlo al caricamento della pagina o da un timer viene ignorato silenziosamente, quindi viene quasi sempre chiamato dall'interno di un gestore di eventi.
2. Restituisce una Promise. La Promise si risolve quando la modalità a schermo intero ha successo e viene rigettata (con un errore) se il browser rifiuta. Aggiungi sempre un .catch() in modo che un rifiuto non diventi un rigetto non gestito.

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

Questo frammento attiva la modalità a schermo intero per l'elemento video-container quando si fa clic sul pulsante. Il controllo su document.fullscreenEnabled protegge dai browser (o dai contesti incorporati come un <iframe> con sandbox) in cui la funzionalità non è disponibile, e il .catch() segnala qualsiasi rifiuto invece di lasciarlo fallire silenziosamente.

Controllare la navigazione dell'interfaccia utente

requestFullscreen() accetta un oggetto opzioni facoltativo. La proprietà navigationUI suggerisce al browser se mantenere visibili i controlli di navigazione (pulsante indietro, barra degli indirizzi):

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

È solo un suggerimento — il browser è libero di ignorarlo — ma è utile per i giochi e i video in cui si desidera la visualizzazione più immersiva possibile.

Uscire dalla Modalità a Schermo Intero

Una pagina può avere un solo elemento a schermo intero alla volta, quindi non è necessario sapere quale elemento è attivo per uscire — document.exitFullscreen() esce sempre da quello corrente e ripristina il layout normale della pagina:

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

Qui l'utente esce dalla modalità a schermo intero cliccando un pulsante Exit Fullscreen. Il controllo if (document.exitFullscreen) verifica che il metodo esista prima di chiamarlo. Nota che il browser permette anche all'utente di uscire in qualsiasi momento premendo Esc — il tuo codice non controlla questo comportamento, ed è proprio per questo che dovresti ascoltare l'evento fullscreenchange invece di assumere che il tuo pulsante sia l'unico modo per uscire.

Gestire i Cambiamenti della Modalità a Schermo Intero con gli Eventi

La Fullscreen API lancia eventi ogni volta che lo stato cambia, indipendentemente da come è cambiato — il tuo pulsante, il tasto Esc o il browser stesso. Ascoltarli è il modo affidabile per mantenere l'interfaccia utente sincronizzata (ad esempio, sostituire un'icona "entra" con una "esci"):

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

Questo listener registra messaggi nella console in base al fatto che il documento sia o meno in modalità a schermo intero, aiutando gli sviluppatori a capire le transizioni di stato. Dovresti inoltre gestire l'evento fullscreenerror per intercettare i casi in cui il browser nega la richiesta (ad esempio, a causa di restrizioni di sicurezza o cancellazione da parte dell'utente):

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

Qui event.target è l'elemento su cui è stata effettuata la richiesta; leggendo .error su di esso (o semplicemente registrando l'evento) si capisce perché il browser ha rifiutato.

Ora vediamo tutto insieme in un esempio completo e funzionante:

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

Ecco come funziona ogni parte:

• Il gestore "Go Fullscreen" verifica document.fullscreenEnabled e poi chiama element.requestFullscreen() sul contenitore video, gestendo eventuali rifiuti.
• Il gestore "Exit Fullscreen" chiama document.exitFullscreen() per tornare alla normale visualizzazione della pagina.
• updateButtonVisibility() mostra il pulsante di uscita solo mentre un elemento è effettivamente a schermo intero, leggendo document.fullscreenElement.
• Il listener fullscreenchange esegue updateButtonVisibility() ad ogni cambio di stato — incluso quando l'utente preme Esc — in modo che l'interfaccia utente non vada mai fuori sincronia, e il listener fullscreenerror segnala una richiesta rifiutata.

Compatibilità e Supporto dei Browser

La Fullscreen API è supportata da tutti i browser moderni — Chrome, Firefox, Safari, Opera e Edge — usando i metodi standard senza prefisso. Le versioni più vecchie di Safari (e versioni molto datate di Chrome/Edge) usavano il prefisso -webkit- (webkitRequestFullscreen, webkitExitFullscreen). Se devi supportarle, usa il nome con prefisso come fallback:

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

Per stilizzare un elemento mentre è a schermo intero, usa la pseudo-classe CSS :fullscreen:

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

Insidie comuni

• Senza gesto utente, nessuna modalità a schermo intero. Chiamare requestFullscreen() al di fuori di un gestore di clic o tasto viene rifiutato. Attivalo da una vera interazione.
• Gli iframe con sandbox sono bloccati a meno che l'iframe non abbia l'attributo allow="fullscreen".
• Gestisci il rigetto della Promise. Un utente può negare la richiesta, oppure una policy può bloccarla — aggiungi sempre .catch().
• Non fare affidamento solo sul tuo pulsante. Il tasto Esc esce dalla modalità a schermo intero senza coinvolgere il tuo codice, quindi affidati all'evento fullscreenchange per aggiornare l'interfaccia utente.

Conclusione

La Fullscreen API offre un modo pulito e basato sui gesti per consentire a un singolo elemento di occupare lo schermo per video, giochi, presentazioni e gallerie. Ricorda gli elementi essenziali: richiedi da un gesto utente, gestisci la Promise restituita, esci con document.exitFullscreen(), e mantieni la tua interfaccia sincronizzata ascoltando l'evento fullscreenchange invece di presumere come l'utente sia uscito dalla modalità a schermo intero.

Per continuare ad apprendere, esplora gli eventi del browser, la manipolazione del DOM e le Promise, su cui si basa la Fullscreen API.

Esercitazione