Fullscreen API

Die Fullscreen-API hat keine eigenen Schnittstellen. Stattdessen erweitert sie mehrere andere Schnittstellen, um die Methoden, Eigenschaften und Ereignis-Handler hinzuzufügen, die benötigt werden, um Vollbildfunktionalität bereitzustellen. 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 zurück in den Fenstermodus zu wechseln. Gibt ein Promise zurück, das aufgelöst wird, sobald der Vollbildmodus vollständig beendet wurde.

Element.requestFullscreen()

Fordert den User-Agent auf, das angegebene Element (und damit seine Nachkommen) in den Vollbildmodus zu versetzen, wobei alle Benutzeroberflächenelemente des Browsers sowie alle anderen Anwendungen vom Bildschirm entfernt werden. Gibt ein Promise zurück, das aufgelöst wird, sobald der Vollbildmodus aktiviert wurde.

Document.fullscreenElement / ShadowRoot.fullscreenElement

Die Eigenschaft fullscreenElement gibt Ihnen das Element an, das aktuell 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 gibt an, ob es möglich ist, den Vollbildmodus zu aktivieren. Dies ist false, wenn der Vollbildmodus aus irgendeinem Grund nicht verfügbar ist (wie etwa das Merkmal "fullscreen" nicht erlaubt ist oder der Vollbildmodus nicht unterstützt wird).

Document.fullscreen Veraltet

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

Hinweis: Verwenden Sie stattdessen die fullscreenElement Eigenschaft auf dem Document oder ShadowRoot; wenn es nicht null ist, dann ist es ein Element, das derzeit im Vollbildmodus angezeigt wird.

fullscreenchange

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

fullscreenerror

Wird an ein Element gesendet, wenn ein Fehler beim Versuch auftritt, es in den oder aus dem Vollbildmodus zu wechseln.

Die Verfügbarkeit des Vollbildmodus kann mit einer Permissions Policy gesteuert werden. Die Funktion des 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 eingebetteten Browserkontexten, die vom gleichen Ursprung wie das oberste Dokument geladen sind, erlaubt ist.

Benutzer können den Vollbildmodus beenden, indem sie die ESC (oder F11) Taste drücken, anstatt darauf zu warten, dass die Website oder App dies programmgesteuert tut. Stellen Sie sicher, dass Sie irgendwo in Ihrer Benutzeroberfläche geeignete Benutzeroberflächenelemente 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 Fenster- und 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 auf die Enter Taste achtet.

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 der Überprüfung des Wertes des fullscreenElement Attributs des document. In einer realen Implementierung möchten Sie an dieser Stelle die gepräfixelten 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 derzeit im Vollbildmodus ist. Der Wechsel in den Vollbildmodus erfolgt durch Aufrufen von Element.requestFullscreen() auf dem <video> Element.

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

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