JavaScript Fullscreen API

Einführung in die JavaScript Fullscreen API

Die JavaScript Fullscreen API ermöglicht es einer Webseite, den Browser anzuweisen, ein einzelnes Element — und nur dieses Element — auf dem gesamten Bildschirm anzuzeigen, wobei Adressleiste, Tabs und die Benutzeroberfläche des Betriebssystems ausgeblendet werden. Das ist es, was den Vollbild-Button bei Videoplayern, Online-Spielen, Präsentationstools und Bildergalerien antreibt.

Dieses Kapitel erklärt, wie man den Vollbildmodus betritt und verlässt, wie man mit Events auf Vollbildänderungen reagiert, welche Fallstricke auftreten können (die Anforderung einer Benutzergeste, das zurückgegebene Promise und das Styling) sowie die Browserunterstützung. Die wichtigsten Methoden und Eigenschaften sind:

• Element.requestFullscreen() — ein Element anfragen, um den Bildschirm auszufüllen. Gibt ein Promise zurück.
• Document.exitFullscreen() — Vollbild verlassen und zur normalen Seite zurückkehren.
• document.fullscreenElement — das aktuell im Vollbildmodus angezeigte Element oder null, falls keines vorhanden.
• document.fullscreenEnabled — true, wenn Vollbild verfügbar und nicht blockiert ist.
• fullscreenchange / fullscreenerror Events — werden ausgelöst, wenn sich der Zustand ändert oder eine Anfrage fehlschlägt.

Vollbildmodus in JavaScript aktivieren

Um den Vollbildmodus zu betreten, ruft man die Methode requestFullscreen() auf einem beliebigen DOM-Element auf, das man vergrößern möchte — ein Video, ein <div>, ein <canvas>, sogar das gesamte document.documentElement.

Zwei Regeln sind von Anfang an wichtig:

1. Eine Benutzergeste ist erforderlich. Browser akzeptieren requestFullscreen() nur, wenn es innerhalb einer echten Interaktion wie einem Klick oder einem Tastendruck ausgeführt wird. Ein Aufruf beim Laden der Seite oder aus einem Timer wird stillschweigend abgelehnt, weshalb es fast immer innerhalb eines Event-Handlers aufgerufen wird.
2. Es gibt ein Promise zurück. Das Promise wird aufgelöst, wenn der Vollbildmodus erfolgreich ist, und abgelehnt (mit einem Fehler), wenn der Browser die Anfrage verweigert. Immer ein .catch() anhängen, damit eine Ablehnung nicht zu einer unbehandelten Ablehnung wird.

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

Dieses Snippet aktiviert den Vollbildmodus für das Element video-container, wenn der Button geklickt wird. Die Prüfung auf document.fullscreenEnabled schützt vor Browsern (oder eingebetteten Kontexten wie einem per Sandbox eingeschränkten <iframe>), in denen die Funktion nicht verfügbar ist, und das .catch() meldet jede Ablehnung, anstatt sie stillschweigend scheitern zu lassen.

Navigations-UI steuern

requestFullscreen() akzeptiert ein optionales Optionsobjekt. Die Eigenschaft navigationUI gibt einen Hinweis, ob der Browser seine Navigationssteuerelemente (Zurück-Button, URL-Leiste) sichtbar lassen soll:

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

Es ist nur ein Hinweis — der Browser kann ihn ignorieren — aber er ist nützlich für Spiele und Videos, bei denen man die immersivste Ansicht möchte.

Vollbildmodus beenden

Eine Seite kann jeweils nur ein Element im Vollbildmodus haben, daher muss man nicht wissen, welches Element aktiv ist, um den Vollbildmodus zu verlassen — document.exitFullscreen() verlässt immer das aktuelle und gibt die Seite in ihr normales Layout zurück:

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

Hier verlässt der Benutzer den Vollbildmodus durch Klicken auf einen Exit Fullscreen-Button. Die Prüfung if (document.exitFullscreen) bestätigt, dass die Methode existiert, bevor sie aufgerufen wird. Der Browser ermöglicht es dem Benutzer außerdem, den Vollbildmodus jederzeit durch Drücken von Esc zu verlassen — der eigene Code kontrolliert das nicht, weshalb man auf das fullscreenchange-Event hören sollte, anstatt anzunehmen, dass der eigene Button der einzige Ausweg ist.

Vollbildänderungen mit Events behandeln

Die Fullscreen API löst Events aus, sobald sich der Zustand ändert, unabhängig davon, wie die Änderung erfolgte — durch den eigenen Button, die Esc-Taste oder den Browser selbst. Auf sie zu hören ist der zuverlässige Weg, die eigene Benutzeroberfläche synchron zu halten (zum Beispiel um ein „Betreten"-Symbol durch ein „Verlassen"-Symbol zu ersetzen):

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

Dieser Event-Listener schreibt Nachrichten in die Konsole, je nachdem ob das Dokument im Vollbildmodus ist oder nicht, und hilft Entwicklern, die Zustandsübergänge zu verstehen. Zusätzlich sollte das fullscreenerror-Event behandelt werden, um Fälle abzufangen, in denen der Browser die Anfrage ablehnt (z. B. aufgrund von Sicherheitseinschränkungen oder Benutzerabbruch):

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

Hier ist event.target das Element, für das die Anfrage gestellt wurde; das Lesen von .error darauf (oder einfaches Protokollieren des Events) zeigt, warum der Browser abgelehnt hat.

Nun setzen wir alles in einem vollständigen, funktionierenden Beispiel zusammen:

Ein vollständiges Beispiel

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

So funktioniert jeder Teil:

• Der „Go Fullscreen"-Handler prüft document.fullscreenEnabled und ruft dann element.requestFullscreen() auf dem Video-Container auf, wobei jede Ablehnung abgefangen wird.
• Der „Exit Fullscreen"-Handler ruft document.exitFullscreen() auf, um zur normalen Seite zurückzukehren.
• updateButtonVisibility() zeigt den Exit-Button nur an, solange tatsächlich ein Element im Vollbildmodus ist, indem document.fullscreenElement gelesen wird.
• Der fullscreenchange-Listener führt updateButtonVisibility() bei jeder Zustandsänderung aus — auch wenn der Benutzer Esc drückt — damit die Benutzeroberfläche nie außer Sync gerät, und der fullscreenerror-Listener meldet eine abgelehnte Anfrage.

Kompatibilität und Browserunterstützung

Die Fullscreen API wird von allen modernen Browsern unterstützt — Chrome, Firefox, Safari, Opera und Edge — mithilfe der standardmäßigen, nicht vorgepfixten Methoden. Ältere Safari-Versionen (und sehr alte Chrome/Edge-Versionen) verwendeten das -webkit--Präfix (webkitRequestFullscreen, webkitExitFullscreen). Wenn man diese unterstützen muss, fällt man auf den vorgepfixten Namen zurück:

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

Um ein Element im Vollbildmodus zu stylen, verwendet man die CSS-Pseudoklasse :fullscreen:

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

Häufige Fallstricke

• Keine Benutzergeste, kein Vollbild. Der Aufruf von requestFullscreen() außerhalb eines Klick- oder Tastatur-Handlers wird abgelehnt. Es muss aus einer echten Interaktion ausgelöst werden.
• Per Sandbox eingeschränkte iframes sind blockiert, es sei denn, der iframe hat das Attribut allow="fullscreen".
• Die Promise-Ablehnung behandeln. Ein Benutzer kann die Anfrage ablehnen, oder eine Richtlinie kann sie blockieren — immer .catch() hinzufügen.
• Nicht nur auf den eigenen Button vertrauen. Die Esc-Taste verlässt den Vollbildmodus ohne Berührung des eigenen Codes, daher sollte man auf das fullscreenchange-Event vertrauen, um die Benutzeroberfläche zu aktualisieren.

Fazit

Die Fullscreen API bietet eine saubere, gestengesteuerte Möglichkeit, ein einzelnes Element für Videos, Spiele, Präsentationen und Galerien den Bildschirm übernehmen zu lassen. Die wesentlichen Punkte sind: aus einer Benutzergeste heraus anfragen, das zurückgegebene Promise behandeln, mit document.exitFullscreen() beenden und die Benutzeroberfläche durch Hören auf das fullscreenchange-Event synchron halten, anstatt anzunehmen, wie der Benutzer den Vollbildmodus verlassen hat.

Um weiterzulernen, erkunde Browser-Events, DOM-Manipulation und Promises, auf denen die Fullscreen API aufbaut.

Übungen