JavaScript Fullscreen API

Introduction à la JavaScript Fullscreen API

La JavaScript Fullscreen API permet à une page web de demander au navigateur d'afficher un seul élément — et uniquement cet élément — en utilisant tout l'écran, en masquant la barre d'adresse, les onglets et le chrome du système d'exploitation. C'est ce qui alimente le bouton plein écran que vous voyez sur les lecteurs vidéo, les jeux en ligne, les outils de présentation et les galeries d'images.

Ce chapitre explique comment entrer et quitter le plein écran, comment réagir aux changements de plein écran avec des événements, les pièges que vous rencontrerez (l'exigence de geste utilisateur, la Promise qu'elle retourne et le style), ainsi que la compatibilité des navigateurs. Les principales méthodes et propriétés sont :

• Element.requestFullscreen() — demande à un élément d'occuper tout l'écran. Retourne une Promise.
• Document.exitFullscreen() — quitte le plein écran et revient à la page normale.
• document.fullscreenElement — l'élément actuellement affiché en plein écran, ou null si aucun.
• document.fullscreenEnabled — true si le plein écran est disponible et non bloqué.
• fullscreenchange / fullscreenerror — événements qui se déclenchent lorsque l'état change ou qu'une demande échoue.

Activer le mode plein écran en JavaScript

Pour entrer en plein écran, appelez la méthode requestFullscreen() sur n'importe quel élément du DOM que vous souhaitez agrandir — une vidéo, un <div>, un <canvas>, voire l'intégralité du document.documentElement.

Deux règles s'appliquent dès le départ :

1. Un geste utilisateur est requis. Les navigateurs n'honorent requestFullscreen() que lorsqu'il s'exécute dans le cadre d'une vraie interaction, comme un clic ou une pression de touche. L'appeler au chargement de la page ou depuis un minuteur est silencieusement rejeté ; il est donc presque toujours appelé depuis un gestionnaire d'événements.
2. Elle retourne une Promise. La Promise se résout lorsque le plein écran réussit et est rejetée (avec une erreur) si le navigateur refuse. Ajoutez toujours un .catch() pour qu'un refus ne devienne pas un rejet non géré.

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

Cet extrait déclenche le plein écran pour l'élément video-container lorsque le bouton est cliqué. La vérification de document.fullscreenEnabled protège contre les navigateurs (ou les contextes embarqués comme un <iframe> sandboxé) où la fonctionnalité est indisponible, et le .catch() signale tout refus plutôt que de le laisser échouer silencieusement.

Contrôler l'interface de navigation

requestFullscreen() accepte un objet d'options facultatif. La propriété navigationUI indique si le navigateur doit conserver ses contrôles de navigation (bouton retour, barre URL) visibles :

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

Il ne s'agit que d'un indice — le navigateur est libre de l'ignorer — mais c'est utile pour les jeux et les vidéos où vous souhaitez l'expérience la plus immersive possible.

Quitter le mode plein écran

Une page ne peut avoir qu'un seul élément en plein écran à la fois, donc vous n'avez pas besoin de savoir quel élément est actif pour quitter — document.exitFullscreen() quitte toujours l'élément courant et remet la page dans sa mise en page normale :

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

Ici, l'utilisateur quitte le plein écran en cliquant sur un bouton Exit Fullscreen. La vérification if (document.exitFullscreen) confirme que la méthode existe avant de l'appeler. Notez que le navigateur permet également à l'utilisateur de quitter à tout moment en appuyant sur Echap — votre code ne contrôle pas cela, c'est précisément pourquoi vous devriez écouter l'événement fullscreenchange plutôt que de supposer que votre bouton est le seul moyen de sortir.

Gérer les changements de plein écran avec des événements

La Fullscreen API déclenche des événements chaque fois que l'état change, quelle qu'en soit la cause — votre bouton, la touche Echap ou le navigateur lui-même. Les écouter est la manière fiable de garder votre interface synchronisée (par exemple, échanger une icône « entrer » contre une icône « quitter ») :

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

Cet écouteur d'événements enregistre des messages dans la console selon que le document est en plein écran ou non, aidant les développeurs à comprendre les transitions d'état. De plus, vous devriez gérer l'événement fullscreenerror pour intercepter les cas où le navigateur refuse la demande (par exemple, en raison de restrictions de sécurité ou d'une annulation par l'utilisateur) :

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

Ici, event.target est l'élément sur lequel la demande a été effectuée ; lire .error dessus (ou simplement enregistrer l'événement) vous indique pourquoi le navigateur a refusé.

Assemblons maintenant le tout dans un exemple complet et fonctionnel :

Un exemple complet

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

Voici comment chaque partie fonctionne :

• Le gestionnaire « Go Fullscreen » vérifie document.fullscreenEnabled puis appelle element.requestFullscreen() sur le conteneur vidéo, en interceptant tout rejet.
• Le gestionnaire « Exit Fullscreen » appelle document.exitFullscreen() pour revenir à la page normale.
• updateButtonVisibility() affiche le bouton de sortie uniquement lorsqu'un élément est réellement en plein écran, en lisant document.fullscreenElement.
• L'écouteur fullscreenchange exécute updateButtonVisibility() à chaque changement d'état — y compris lorsque l'utilisateur appuie sur Echap — de sorte que l'interface ne se désynchronise jamais, et l'écouteur fullscreenerror signale une demande refusée.

Compatibilité et prise en charge des navigateurs

La Fullscreen API est prise en charge par tous les navigateurs modernes — Chrome, Firefox, Safari, Opera et Edge — en utilisant les méthodes standard sans préfixe. Les anciennes versions de Safari (et les très anciennes versions de Chrome/Edge) utilisaient le préfixe -webkit- (webkitRequestFullscreen, webkitExitFullscreen). Si vous devez prendre en charge ces navigateurs, utilisez le nom avec préfixe comme solution de repli :

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

Pour styliser un élément lorsqu'il est en plein écran, utilisez la pseudo-classe CSS :fullscreen :

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

Pièges courants

• Pas de geste utilisateur, pas de plein écran. Appeler requestFullscreen() en dehors d'un gestionnaire de clic ou de touche est rejeté. Déclenchez-le depuis une vraie interaction.
• Les iframes sandboxées sont bloquées sauf si l'iframe porte l'attribut allow="fullscreen".
• Gérez le rejet de la Promise. Un utilisateur peut refuser la demande, ou une politique peut la bloquer — ajoutez toujours .catch().
• Ne faites pas confiance à votre seul bouton. La touche Echap quitte le plein écran sans toucher à votre code, alors fiez-vous à l'événement fullscreenchange pour mettre à jour l'interface.

Conclusion

La Fullscreen API vous offre un moyen propre, piloté par les gestes, de laisser un seul élément prendre le contrôle de l'écran pour les vidéos, les jeux, les présentations et les galeries. Retenez l'essentiel : faites la demande depuis un geste utilisateur, gérez la Promise retournée, quittez avec document.exitFullscreen(), et gardez votre interface synchronisée en écoutant l'événement fullscreenchange plutôt qu'en supposant comment l'utilisateur a quitté le plein écran.

Pour continuer à apprendre, explorez les événements navigateur, la manipulation du DOM et les Promises, sur lesquels la Fullscreen API s'appuie.

Pratique