Leitfaden zur Fullscreen-API

Angenommen, Sie haben ein Element, das Sie im Vollbildmodus präsentieren möchten (zum Beispiel ein <video>), können Sie es im Vollbildmodus anzeigen, indem Sie seine 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 wie folgt im Vollbildmodus anzeigen:

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

Dieser Code überprüft, ob die Methode requestFullscreen() existiert, bevor sie aufgerufen wird.

Wenn der Vollbildmodus erfolgreich aktiviert wird, erhält das Dokument, das das Element enthält, ein fullscreenchange-Ereignis. Wenn der Vollbildmodus verlassen wird, erhält das Dokument erneut ein fullscreenchange-Ereignis. Beachten Sie, dass das fullscreenchange-Ereignis keine Informationen darüber liefert, ob das Dokument den Vollbildmodus betritt oder verlässt. Wenn das Dokument jedoch ein nicht null fullscreenElement hat, wissen Sie, dass Sie sich im Vollbildmodus befinden.

Es ist nicht garantiert, dass Sie in der Lage sind, in den Vollbildmodus zu wechseln. Zum Beispiel haben <iframe>-Elemente das allowfullscreen-Attribut, um auszuwählen, ob ihr Inhalt im Vollbildmodus angezeigt werden darf. Darüber hinaus können bestimmte Arten von Inhalten, wie z.B. fensterorientierte Plug-ins, nicht im Vollbildmodus dargestellt werden. Der Versuch, ein Element, das nicht im Vollbildmodus angezeigt werden kann (oder ein Eltern- oder Nachfahrelement eines solchen Elements), im Vollbildmodus darzustellen, funktioniert nicht. Stattdessen erhält das Element, das den Vollbildmodus angefordert hat, ein fullscreenerror-Ereignis. Wenn eine Vollbildanfrage fehlschlägt, protokolliert Firefox eine Fehlermeldung in der Webkonsole, die erklärt, warum die Anfrage fehlgeschlagen ist. In Chrome und neueren Versionen von Opera wird jedoch keine solche Warnung erzeugt.

Der Benutzer hat immer die Möglichkeit, den Vollbildmodus nach eigenem Ermessen zu verlassen; siehe Was Ihre Benutzer wissen möchten. Sie können dies auch programmatisch durch Aufruf der Methode Document.exitFullscreen() tun.

Das Document stellt einige zusätzliche Informationen bereit, die bei der Entwicklung von Webanwendungen im Vollbildmodus nützlich sein können:

Document.fullscreenElement / ShadowRoot.fullscreenElement

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

Document.fullscreenEnabled

Die fullscreenEnabled-Eigenschaft gibt an, ob das Dokument sich derzeit in einem Zustand befindet, der es ermöglichen würde, den Vollbildmodus anzufordern.

Einige mobile Browser ignorieren im Vollbildmodus die Einstellungen des Viewport-Meta-Tags und blockieren die Skalierung durch den Benutzer; beispielsweise kann eine „Pinch-to-Zoom“-Geste auf einer Seite, die im Vollbildmodus präsentiert wird, nicht funktionieren — auch wenn die Seite, wenn sie nicht im Vollbildmodus ist, mit „Pinch-to-Zoom“ skaliert werden kann.

Sie sollten Ihre Benutzer darüber informieren, dass sie die Esc-Taste (oder F11) drücken können, um den Vollbildmodus zu verlassen.

Darüber hinaus führt das Navigieren zu einer anderen Seite, das Wechseln der Tabs oder das Umschalten zu einer anderen Anwendung (zum Beispiel durch Alt-Tab) im Vollbildmodus ebenfalls zum Verlassen des Vollbildmodus.

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

Live-Beispiele anzeigen

Wenn die Seite geladen wird, wird dieser Code ausgeführt, um einen Ereignislistener einzurichten, der die Enter-Taste überwacht.

document.addEventListener(
  "keydown",
  (e) => {
    if (e.key === "Enter") {
      toggleFullScreen();
    }
  },
  false,
);

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

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

Dies beginnt mit der Prüfung des Werts des fullscreenElement-Attributs im document. Wenn es null ist, befindet sich das Dokument derzeit im Fenstermodus, und wir müssen in den Vollbildmodus wechseln. Der Wechsel in den Vollbildmodus erfolgt durch Aufruf von Element.requestFullscreen().

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

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