Leitfaden zur Fullscreen-API

Um ein Element im Vollbildmodus darzustellen (wie beispielsweise ein <video>), können Sie dessen Methode requestFullscreen() aufrufen.

Betrachten wir dieses <video>-Element:

<video controls id="my-video">
  <source src="somevideo.webm" />
  <source src="somevideo.mp4" />
</video>

Wir können dieses Video folgendermaßen in den Vollbildmodus versetzen:

const elem = document.getElementById("my-video");
if (elem.requestFullscreen) {
  elem.requestFullscreen();
}

Dieser Code überprüft das Vorhandensein der Methode requestFullscreen(), bevor sie aufgerufen wird.

Sobald ein Element im Vollbildmodus ist, wird es durch :fullscreen erkannt, was ihm einige Standardstile verleiht, wie etwa die komplette Ausfüllung des Bildschirms. Es wird auch in der obersten Ebene platziert.

Wenn mehrere Elemente im Vollbildmodus dargestellt werden sollen, werden sie alle durch :fullscreen erkannt und befinden sich alle in der obersten Ebene. Sie stapeln sich, wobei die zuletzt angeforderten Elemente oben auf den älteren liegen. Das zuletzt angeforderte Element wird angezeigt und durch Document.fullscreenElement zurückgegeben.

Wenn der Vollbildmodus erfolgreich aktiviert wird, erhält das Dokument, das das Element enthält, ein fullscreenchange-Ereignis. Wenn der Vollbildmodus beendet wird, erhält das Dokument erneut ein fullscreenchange-Ereignis. Beachten Sie, dass das fullscreenchange-Ereignis selbst keine Informationen darüber liefert, ob das Dokument in den oder aus dem Vollbildmodus wechselt. Aber wenn das Dokument ein nicht-null fullscreenElement besitzt, wissen Sie, dass Sie sich im Vollbildmodus befinden.

Es ist nicht garantiert, dass der Wechsel in den Vollbildmodus gelingt. Zum Beispiel haben <iframe>-Elemente das allowfullscreen-Attribut, um sich bewusst dafür zu entscheiden, ihren Inhalt im Vollbildmodus darzustellen. Zusätzlich können bestimmte Arten von Inhalten, wie fensterbasierte Plug-ins, nicht im Vollbildmodus angezeigt werden. Der Versuch, ein Element im Vollbildmodus darzustellen, das nicht angezeigt werden kann (oder dessen Eltern- oder Kinderelement dies nicht kann), wird nicht funktionieren. Stattdessen erhält das Element, das Vollbild angefordert hat, ein fullscreenerror-Ereignis. Wenn eine Vollbildanforderung fehlschlägt, protokolliert Firefox eine Fehlermeldung in der Webkonsole, die erklärt, warum die Anforderung fehlgeschlagen ist. In Chrome und neueren Versionen von Opera wird jedoch keine solche Warnung generiert.

Der Benutzer hat jederzeit die Möglichkeit, den Vollbildmodus aus eigener Initiative zu verlassen; siehe Dinge, die Ihre Benutzer wissen möchten. Sie können dies auch programmatisch tun, indem Sie die Methode Document.exitFullscreen() aufrufen.

Wenn sich mehrere Elemente im Vollbildmodus befinden, beendet der Aufruf von exitFullscreen() nur das oberste Element und gibt das darunterliegende Element frei. Das Drücken von Esc oder F11 beendet alle Vollbildelemente.

Das Document bietet einige zusätzliche Informationen, die beim Entwickeln von Webanwendungen im Vollbildmodus nützlich sein können:

Document.fullscreenElement / ShadowRoot.fullscreenElement

Die fullscreenElement-Eigenschaft gibt Ihnen das Element an, das derzeit im Vollbildmodus angezeigt wird. Wenn dieser Wert nicht null ist, befindet sich das Dokument (oder der Shadow-DOM) im Vollbildmodus. Ist dieser Wert null, befindet sich das Dokument (oder der Shadow-DOM) nicht im Vollbildmodus.

Document.fullscreenEnabled

Die fullscreenEnabled-Eigenschaft zeigt an, ob das Dokument derzeit in einem Zustand ist, der den Anruf des Vollbildmodus zulassen würde.

Einige mobile Browser ignorieren im Vollbildmodus die Einstellungen des Viewport-Meta-Tags und blockieren das Skalieren durch den Benutzer; zum Beispiel könnte eine "Pinch-to-Zoom"-Geste auf einer Seite im Vollbildmodus nicht funktionieren — selbst wenn sie im Normalmodus skalierbar ist.

Stellen Sie sicher, dass Ihre Benutzer wissen, dass sie die Esc-Taste (oder F11) drücken können, um den Vollbildmodus zu verlassen.

Zudem führt das Navigieren zu einer anderen Seite, das Wechseln von Tabs oder das Wechseln zu einer anderen Anwendung (zum Beispiel mit Alt-Tab) während des Vollbildmodus ebenfalls zum Beenden des Vollbilds.

In diesem Beispiel wird ein Video auf einer Webseite dargestellt. Das Drücken der Return- oder Enter-Taste ermöglicht es dem Benutzer, zwischen Fenstermodus und Vollbildmodus des Videos zu wechseln.

Live-Beispiele ansehen

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,
);

Dieser Code wird aufgerufen, wenn der Benutzer, wie oben beschrieben, die Enter-Taste drückt.

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

Dies beginnt damit, den Wert des fullscreenElement-Attributs im document zu überprüfen. Ist es null, befindet sich das Dokument derzeit im Fenstermodus, daher müssen wir in den Vollbildmodus wechseln. Der Wechsel in den Vollbildmodus erfolgt durch den Aufruf von Element.requestFullscreen().

Wenn der Vollbildmodus bereits aktiv ist (fullscreenElement ist nicht-null), rufen wir document.exitFullscreen() auf.

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