Fullscreen API
Eingeschränkt verfügbar
Diese Funktion ist nicht Baseline, da sie in einigen der am weitesten verbreiteten Browser nicht funktioniert.
Die Fullscreen-API fügt Methoden hinzu, um ein bestimmtes Element (und seine Nachkommen) im Vollbildmodus anzuzeigen und den Vollbildmodus zu verlassen, wenn er nicht mehr benötigt wird. Dies ermöglicht es, gewünschte Inhalte – wie beispielsweise ein Online-Spiel – auf dem gesamten Bildschirm des Benutzers darzustellen, wodurch alle Benutzeroberflächenelemente des Browsers und andere Anwendungen vom Bildschirm entfernt werden, bis der Vollbildmodus beendet wird.
Lesen Sie den Artikel Leitfaden zur Fullscreen-API für Details zur Verwendung 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 zur Bereitstellung der Vollbildfunktionalität benötigt werden. Diese sind in den folgenden Abschnitten aufgeführt.
Instanz-Methoden
Die Fullscreen-API fügt den Document und Element-Schnittstellen Methoden hinzu, um den Vollbildmodus ein- und auszuschalten.
Instanz-Methoden in der Document-Schnittstelle
Document.exitFullscreen()-
Fordert, dass der Benutzer-Agent vom Vollbildmodus in den Fenstermodus wechselt. Gibt ein
Promisezurück, welches aufgelöst wird, sobald der Vollbildmodus vollständig beendet ist.
Instanz-Methoden in der Element-Schnittstelle
Element.requestFullscreen()-
Fordert den Benutzer-Agent auf, das angegebene Element (und damit auch seine Nachkommen) in den Vollbildmodus zu versetzen, wodurch alle UI-Elemente des Browsers sowie alle anderen Anwendungen vom Bildschirm entfernt werden. Gibt ein
Promisezurück, welches aufgelöst wird, sobald der Vollbildmodus aktiviert wurde.
Instanz-Eigenschaften
Document.fullscreenElement/ShadowRoot.fullscreenElement-
Die Eigenschaft
fullscreenElementgibt dasElementan, das momentan im Vollbildmodus im DOM (oder Shadow DOM) angezeigt wird. Wenn diesnullist, befindet sich das Dokument (oder Shadow DOM) nicht im Vollbildmodus. Document.fullscreenEnabled-
Die Eigenschaft
fullscreenEnabledgibt an, ob es möglich ist, in den Vollbildmodus zu wechseln. Dies istfalse, 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.fullscreenVeraltet-
Ein Boolescher Wert, der
trueist, wenn das Dokument ein Element hat, das momentan im Vollbildmodus angezeigt wird; andernfalls gibt erfalsezurück.Hinweis: Verwenden Sie stattdessen die Eigenschaft
fullscreenElementauf demDocumentoderShadowRoot; wenn es nichtnullist, dann handelt es sich um einElement, das momentan im Vollbildmodus angezeigt wird.
Ereignisse
fullscreenchange-
Wird an ein
Elementgesendet, wenn es in den oder aus dem Vollbildmodus wechselt. fullscreenerror-
Wird an ein
Elementgesendet, wenn ein Fehler beim Wechseln in den oder aus dem Vollbildmodus auftritt.
Zugriffskontrolle
Die Verfügbarkeit des Vollbildmodus kann mit einer Berechtigungsrichtlinie gesteuert werden. Das Feature für den Vollbildmodus wird durch den String "fullscreen" identifiziert, mit einem standardmäßigen Allowlist-Wert von "self", was bedeutet, dass der Vollbildmodus in höchstebenen Dokumentenkontexten sowie in eingebetteten Browsing-Kontexten erlaubt ist, die von derselben Herkunft wie das oberste Dokument geladen werden.
Verwendungshinweise
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 in Ihrer Benutzeroberfläche geeignete Elemente bereitstellen, die den Benutzer darüber informieren, dass diese Möglichkeit besteht.
Hinweis: Das Navigieren zu einer anderen Seite, das Wechseln von Tabs oder das Umschalten zu einer anderen Anwendung über einen beliebigen Anwendungsumschalter (oder Alt-Tab) wird ebenfalls den Vollbildmodus beenden.
Beispiele
Einfache Nutzung des Vollbildmodus
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.
Überwachen der Enter-Taste
Wenn die Seite geladen ist, wird dieser Code ausgeführt, um einen Ereignislistener einzurichten, der auf die Enter-Taste achtet.
const video = document.getElementById("video");
// On pressing ENTER call toggleFullScreen method
document.addEventListener("keydown", (e) => {
if (e.key === "Enter") {
toggleFullScreen(video);
}
});
Umschalten des Vollbildmodus
Dieser Code wird von dem oben genannten Ereignishandler aufgerufen, wenn der Benutzer die Enter-Taste drückt.
function toggleFullScreen(video) {
if (!document.fullscreenElement) {
// If the document is not in full screen mode
// make the video full screen
video.requestFullscreen();
} else {
// Otherwise exit the full screen
document.exitFullscreen?.();
}
}
Das beginnt mit der Untersuchung des Wertes des fullscreenElement-Attributs des document. Wenn der Wert null ist, befindet sich das Dokument derzeit im Fenstermodus, weshalb wir in den Vollbildmodus wechseln müssen; andernfalls ist es das Element, das derzeit im Vollbildmodus ist. 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.