Fullscreen API

Die Fullscreen API hat keine eigenen Schnittstellen. Stattdessen erweitert sie mehrere andere Schnittstellen, um die Methoden, Eigenschaften und Ereignishandler hinzuzufügen, die für die Bereitstellung der Vollbildfunktionalität erforderlich sind. Diese sind in den folgenden Abschnitten aufgeführt.

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

Document.exitFullscreen()

Fordert den User Agent auf, vom Vollbildmodus zurück zum 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 seine Nachfahren) in den Vollbildmodus zu versetzen, wodurch alle UI-Elemente des Browsers sowie alle anderen Anwendungen vom Bildschirm entfernt werden. Gibt ein Promise zurück, das aufgelöst wird, sobald der Vollbildmodus aktiviert ist.

Document.fullscreenElement / ShadowRoot.fullscreenElement

Die Eigenschaft fullscreenElement gibt Ihnen das Element an, das 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 gibt an, ob es möglich ist, den Vollbildmodus zu aktivieren. Dies ist false, wenn der Vollbildmodus aus irgendeinem Grund nicht verfügbar ist (z. B. wenn die Funktion "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 derzeit im Vollbildmodus angezeigt wird; andernfalls wird false zurückgegeben.

Hinweis: Verwenden Sie stattdessen die Eigenschaft fullscreenElement auf dem Document oder ShadowRoot; wenn es nicht null ist, handelt es sich um 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 auftritt, während versucht wird, es in den oder aus dem Vollbildmodus zu schalten.

Die Verfügbarkeit des Vollbildmodus kann über eine Permissions Policy gesteuert werden. Die Vollbildmodus-Funktion wird durch den String "fullscreen" identifiziert, mit einem Standard-Zulassungswert von "self", was bedeutet, dass der Vollbildmodus in Dokumentenkontexten der obersten Ebene sowie in geschachtelten Browsing-Kontexten erlaubt ist, die vom selben Ursprung wie das oberste Dokument geladen werden.

Benutzer können den Vollbildmodus durch Drücken der ESC (oder F11)-Taste beenden, anstatt zu warten, dass die Website oder Anwendung 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 zur Verfügung steht.

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

Live-Beispiel ansehen

Überwachung der Enter-Taste

Wenn die Seite geladen wird, 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 Ereignishandler aufgerufen, wenn der Benutzer die Enter-Taste drückt.

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

Dieser beginnt mit der Überprüfung des Werts des fullscreenElement-Attributs des document. In einem realen Einsatz sollten Sie zu diesem Zeitpunkt auch nach prefixed Versionen hiervon (wie mozFullScreenElement, msFullscreenElement oder webkitFullscreenElement) suchen. Wenn der Wert null ist, befindet sich das Dokument derzeit im Fenstermodus und wir müssen in den Vollbildmodus wechseln; 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() auf dem document auf, um den Vollbildmodus zu beenden.

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