Fullscreen API

Die Fullscreen API fügt Methoden hinzu, um ein spezifisches Element (und seine Nachfahren) im Vollbildmodus darzustellen und um den Vollbildmodus zu beenden, wenn er nicht mehr benötigt wird. Dies ermöglicht es, Inhalte wie beispielsweise ein Online-Spiel über den gesamten Bildschirm des Benutzers anzeigen zu lassen und dabei alle Benutzeroberflächenelemente des Browsers und andere Anwendungen vom Bildschirm zu entfernen, bis der Vollbildmodus beendet wird.

Siehe den Artikel Leitfaden zur Fullscreen API für Details zur Nutzung der API.

Schnittstellen

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.

Instanzmethoden

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

Instanzmethoden auf der Document-Schnittstelle

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.

Instanzmethoden auf der Element-Schnittstelle

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.

Instanzeigenschaften

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

Veraltete Eigenschaften

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.

Ereignisse

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.

Steuerung des Zugriffs

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.

Nutzungshinweise

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.

Hinweis: Das Navigieren zu einer anderen Seite, der Wechsel zwischen Tabs oder das Umschalten zu einer anderen Anwendung mit einem Anwendungswechsler (oder Alt-Tab) führt ebenfalls dazu, dass der Vollbildmodus verlassen wird.

Beispiele

Einfacher Vollbildmodus

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.

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

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

Spezifikationen

Specification
Fullscreen API Standard
# ref-for-dom-document-fullscreenelement①
Fullscreen API Standard
# ref-for-dom-document-fullscreenenabled①
Fullscreen API Standard
# ref-for-dom-document-exitfullscreen①
Fullscreen API Standard
# ref-for-dom-element-requestfullscreen①
Fullscreen API Standard
# dom-document-fullscreen

Browser-Kompatibilität

api.Document.fullscreenElement

BCD tables only load in the browser

api.Document.fullscreenEnabled

BCD tables only load in the browser

api.Document.exitFullscreen

BCD tables only load in the browser

api.Element.requestFullscreen

BCD tables only load in the browser

api.Document.fullscreen

BCD tables only load in the browser

Siehe auch