Fullscreen API

Die Fullscreen-API hat keine eigenen Schnittstellen. Stattdessen ergänzt sie mehrere andere Schnittstellen, um die Methoden, Eigenschaften und Ereignis-Handler hinzuzufügen, die für die Unterstützung der Vollbildfunktionalität benötigt werden. Diese sind in den folgenden Abschnitten aufgeführt.

Die Fullscreen-API fügt den Schnittstellen Document und Element Methoden hinzu, um den Vollbildmodus ein- und auszuschalten.

Document.exitFullscreen()

Fordert den User-Agent auf, vom Vollbildmodus in den Fenstermodus zu wechseln. Gibt ein Promise zurück, das aufgelöst wird, sobald der Vollbildmodus vollständig beendet ist.

Element.requestFullscreen()

Fordert den User-Agent auf, das angegebene Element (und damit auch dessen Nachkommen) im Vollbildmodus anzuzeigen und alle UI-Elemente des Browsers sowie andere Anwendungen vom Bildschirm zu entfernen. Gibt ein Promise zurück, das aufgelöst wird, sobald der Vollbildmodus aktiviert wurde.

Document.fullscreenElement / ShadowRoot.fullscreenElement

Die Eigenschaft fullscreenElement teilt Ihnen mit, welches Element derzeit im Vollbildmodus im DOM (oder Shadow-DOM) angezeigt wird. Wenn dies null ist, befindet sich das Dokument (oder Shadow-DOM) nicht im Vollbildmodus.

Document.fullscreenEnabled

Die Eigenschaft fullscreenEnabled teilt Ihnen mit, ob es möglich ist, in den Vollbildmodus zu wechseln. Dies ist false, wenn der Vollbildmodus aus irgendeinem Grund nicht verfügbar ist (z. B. wenn das Merkmal "fullscreen" nicht erlaubt ist oder der Vollbildmodus nicht unterstützt wird).

Document.fullscreen Veraltet

Ein Boolean-Wert, der true ist, wenn das Dokument ein Element hat, das derzeit im Vollbildmodus angezeigt wird; andernfalls wird false zurückgegeben.

Hinweis: Verwenden Sie stattdessen die fullscreenElement-Eigenschaft des Document oder ShadowRoot; wenn sie nicht null ist, wird ein Element, das derzeit im Vollbildmodus angezeigt wird.

fullscreenchange

Wird einem Element gesendet, wenn es in den oder aus dem Vollbildmodus wechselt.

fullscreenerror

Wird an ein Element gesendet, wenn ein Fehler auftritt, während versucht wird, es in den oder aus dem Vollbildmodus zu schalten.

Die Verfügbarkeit des Vollbildmodus kann über eine Berechtigungsrichtlinie gesteuert werden. Die Funktion Vollbildmodus wird durch die Zeichenkette "fullscreen" identifiziert, mit einem Standard-Wert von "self", was bedeutet, dass der Vollbildmodus in Dokumentkontexten der obersten Ebene sowie in geschachtelten Kontexten erlaubt ist, die vom gleichen Ursprung wie das oberste Dokument geladen wurden.

Benutzer können den Vollbildmodus verlassen, indem sie die ESC- (oder F11-) Taste drücken, anstatt darauf zu warten, dass die Website oder App dies programmatisch durchführt. Stellen Sie sicher, dass Sie an einer geeigneten Stelle in Ihrer Benutzeroberfläche entsprechende UI-Elemente bereitstellen, die den Benutzer darüber informieren, dass diese Option verfügbar ist.

In diesem Beispiel wird ein Video auf einer Webseite präsentiert. Durch Drücken der Enter-Taste kann der Benutzer zwischen der Fenster- und der Vollbilddarstellung des Videos umschalten.

Live-Beispiel ansehen

Überwachung der Enter-Taste

Wenn die Seite geladen ist, wird dieser Code ausgeführt, um einen Ereignis-Listener einzurichten, der die Enter-Taste überwacht.

document.addEventListener(
  "keydown",
  (e) => {
    if (e.key === "Enter") {
      toggleFullScreen();
    }
  },
  false,
);

Umschalten des Vollbildmodus

Dieser Code wird von dem oben genannten Ereignis-Handler aufgerufen, wenn der Benutzer die Enter-Taste drückt.

function toggleFullScreen() {
  if (!document.fullscreenElement) {
    document.documentElement.requestFullscreen();
  } else if (document.exitFullscreen) {
    document.exitFullscreen();
  }
}

Dies beginnt mit dem Überprüfen des Werts des fullscreenElement-Attributs des document. In einer realen Umgebung möchten Sie an dieser Stelle auch auf Präfix-Versionen überprüfen (mozFullScreenElement, msFullscreenElement oder webkitFullscreenElement zum Beispiel). Wenn der Wert null ist, befindet sich das Dokument derzeit im Fenstermodus, sodass wir in den Vollbildmodus wechseln müssen; andernfalls ist es das Element, das sich derzeit im Vollbildmodus befindet. Der Wechsel in den Vollbildmodus erfolgt durch Aufruf von Element.requestFullscreen() auf dem <video>-Element.

Wenn der Vollbildmodus bereits aktiv ist (fullscreenElement ist nicht null), rufen wir exitFullscreen() auf dem document auf, um den Vollbildmodus zu beenden.

• Element.requestFullscreen()
• Document.exitFullscreen()
• Document.fullscreen
• Document.fullscreenElement
• :fullscreen, ::backdrop
• allowfullscreen