Fullscreen API

Eingeschränkt verfügbar

Diese Funktion ist nicht Baseline, da sie in einigen der am weitesten verbreiteten Browser nicht funktioniert.

Want more browser support for this feature? Tell us why.

Die Fullscreen API stellt Methoden bereit, mit denen ein bestimmtes Element (und seine Nachfahren) im Vollbildmodus angezeigt und der Vollbildmodus wieder beendet werden kann, wenn er nicht mehr benötigt wird. So lassen sich gewünschte Inhalte – etwa ein Onlinespiel – auf dem gesamten Bildschirm des Benutzers anzeigen. Dabei werden alle Elemente der Browseroberfläche und andere Anwendungen vom Bildschirm ausgeblendet, bis der Vollbildmodus beendet wird.

Weitere Informationen zur Verwendung der API finden Sie im Artikel Leitfaden zur Fullscreen API.

Schnittstellen

Die Fullscreen API hat keine eigenen Schnittstellen. Stattdessen erweitert sie mehrere andere Schnittstellen um die Methoden, Eigenschaften und Event-Handler, die für die Vollbildfunktion benötigt werden. Diese werden in den folgenden Abschnitten aufgeführt.

Instanzmethoden

Die Fullscreen API ergänzt die Schnittstellen Document und Element um Methoden zum Aktivieren und Beenden des Vollbildmodus.

Instanzmethoden der Document-Schnittstelle

Document.exitFullscreen(): Fordert den User Agent auf, vom Vollbildmodus in den Fenstermodus zurückzukehren. Gibt ein Promise zurück, das aufgelöst wird, sobald der Vollbildmodus vollständig beendet wurde.

Instanzmethoden der Element-Schnittstelle

Element.requestFullscreen(): Fordert den User Agent auf, das angegebene Element (und damit auch seine Nachfahren) im Vollbildmodus anzuzeigen. Dabei werden alle Elemente der Browseroberfläche sowie andere Anwendungen vom Bildschirm ausgeblendet. Gibt ein Promise zurück, das aufgelöst wird, sobald der Vollbildmodus aktiviert wurde.

Instanzeigenschaften

Document.fullscreenElement / ShadowRoot.fullscreenElement: Die Eigenschaft fullscreenElement gibt das Element an, das derzeit im DOM (oder Shadow DOM) im Vollbildmodus angezeigt wird. Ist der Wert null, befindet sich das Dokument (oder Shadow DOM) nicht im Vollbildmodus.
Document.fullscreenEnabled: Die Eigenschaft fullscreenEnabled gibt an, ob der Vollbildmodus aktiviert werden kann. Ihr Wert ist false, wenn der Vollbildmodus aus irgendeinem Grund nicht verfügbar ist (etwa weil die Funktion "fullscreen" nicht erlaubt ist oder der Vollbildmodus nicht unterstützt wird).

Veraltete Eigenschaften

Document.fullscreen: Ein boolescher Wert, der true ist, wenn im Dokument derzeit ein Element im Vollbildmodus angezeigt wird; andernfalls gibt die Eigenschaft false zurück.

Hinweis: Verwenden Sie stattdessen die Eigenschaft fullscreenElement von Document oder ShadowRoot. Ist ihr Wert nicht null, verweist sie auf ein Element, das derzeit im Vollbildmodus angezeigt wird.

Ereignisse

fullscreenchange: Wird an ein Element gesendet, wenn es in den Vollbildmodus wechselt oder ihn verlässt.
fullscreenerror: Wird an ein Element gesendet, wenn beim Versuch, es in den Vollbildmodus zu versetzen oder diesen zu beenden, ein Fehler auftritt.

Sicherheitsaspekte

Zum Aktivieren des Vollbildmodus ist eine vorübergehende Benutzeraktivierung erforderlich: Der Benutzer muss mit der Seite oder einem UI-Element interagieren, damit diese Funktion verwendet werden kann.

Der Vollbildmodus wird durch die Permissions-Policy-Direktive fullscreen gesteuert.

Die Standard-Allowlist für fullscreen ist self. Damit ist die Verwendung des Vollbildmodus in verschachtelten Frames derselben Origin möglich, in Inhalten von Drittanbietern jedoch nicht. Um die Verwendung durch einen Drittanbieter zu ermöglichen, muss der Server zunächst mit dem Permissions-Policy-Header einer bestimmten Drittanbieter-Origin die Berechtigung erteilen.

http

Permissions-Policy: fullscreen=(self "https://b.example.com")

Anschließend muss das Attribut allow="fullscreen" zum Frame-Container-Element für Quellen dieser Origin hinzugefügt werden:

html

<iframe src="https://b.example.com" allow="fullscreen"></iframe>

Mit der fullscreen-Berechtigung der Permissions API lässt sich prüfen, ob der Zugriff auf den Vollbildmodus granted, denied oder prompt ist (eine Bestätigung durch den Benutzer erfordert).

Beispiele

Einfache Verwendung des Vollbildmodus

In diesem Beispiel wird ein Video auf einer Webseite angezeigt. Durch Drücken der Eingabetaste kann der Benutzer zwischen der Anzeige im Fenster und im Vollbildmodus wechseln.

Live-Beispiel ansehen

Auf die Eingabetaste reagieren

Beim Laden der Seite wird dieser Code ausgeführt, um einen Event-Listener einzurichten, der auf die Eingabetaste reagiert.

const video = document.getElementById("video");

// On pressing ENTER call toggleFullScreen method
document.addEventListener("keydown", (e) => {
  if (e.key === "Enter") {
    toggleFullScreen(video);
  }
});

Zwischen Fenster- und Vollbildmodus wechseln

Dieser Code wird vom obigen Event-Handler aufgerufen, wenn der Benutzer die Eingabetaste 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?.();
  }
}

Zunächst wird der Wert des Attributs fullscreenElement von document geprüft. Ist der Wert null, befindet sich das Dokument derzeit im Fenstermodus und muss in den Vollbildmodus wechseln. Andernfalls verweist der Wert auf das Element, das derzeit im Vollbildmodus angezeigt wird. Der Wechsel in den Vollbildmodus erfolgt durch Aufrufen von Element.requestFullscreen() auf dem <video>-Element.

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

Spezifikationen

Spezifikation
Fullscreen API # ref-for-dom-element-requestfullscreen①

Browser-Kompatibilität

Siehe auch

Help improve MDN

Erfahren Sie, wie Sie beitragen können Diese Seite wurde automatisch aus dem Englischen übersetzt.

Übersetzung auf GitHub anzeigen • Fehler mit dieser Übersetzung melden