Leitfaden zur Fullscreen-API

Um ein Element, das Sie im Vollbildmodus präsentieren möchten (wie z.B. ein <video>), im Vollbildmodus anzuzeigen, rufen Sie die Methode requestFullscreen() auf.

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 das Vorhandensein der Methode requestFullscreen(), bevor er sie aufruft.

Sobald ein Element im Vollbildmodus ist, wird es durch :fullscreen erfasst, was ihm einige Standardstile verleiht, wie z.B. die gesamte Bildschirmfläche einzunehmen. Es wird auch in die Top-Layer verschoben.

Wenn mehrere Elemente im Vollbildmodus angezeigt werden sollen, werden sie alle durch :fullscreen erfasst und befinden sich alle in der Top-Layer. Sie stapeln sich übereinander, wobei die zuletzt angeforderten Elemente über den älteren liegen. Das zuletzt angeforderte Element wird angezeigt und von 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 verlassen 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 Vollbildmodus wechselt oder ihn verlässt, aber wenn das Dokument ein nicht-null fullscreenElement hat, wissen Sie, dass Sie sich im Vollbildmodus befinden.

Es ist nicht garantiert, dass Sie in den Vollbildmodus wechseln können. Zum Beispiel haben <iframe>-Elemente das allowfullscreen Attribut, um das Anzeigen ihres Inhalts im Vollbildmodus zuzulassen. Außerdem können bestimmte Arten von Inhalten, wie beispielsweise Plug-ins mit Fenster, nicht im Vollbildmodus angezeigt werden. Der Versuch, ein Element, das nicht im Vollbildmodus angezeigt werden kann, oder das Eltern- oder Nachfolgeelement eines solchen Elements in den Vollbildmodus zu versetzen, funktioniert nicht. Stattdessen erhält das Element, das den Vollbildmodus angefordert hat, ein fullscreenerror Ereignis. Wenn eine Vollbildanforderung fehlschlägt, protokolliert Firefox eine Fehlermeldung in der Web-Konsole, die erklärt, warum die Anforderung fehlgeschlagen ist. In Chrome und neueren Versionen von Opera wird jedoch keine solche Warnung generiert.

Der Benutzer hat immer die Möglichkeit, den Vollbildmodus selbst 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 ein Aufruf von exitFullscreen() nur das oberste Element und enthüllt das nächste darunter. Durch Drücken von Esc oder F11 werden alle Vollbildelemente beendet.

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 Ihnen das Element an, das derzeit im Vollbildmodus angezeigt wird. Wenn dies nicht null ist, befindet sich das Dokument (oder der Schatten-DOM) im Vollbildmodus. Wenn dies null ist, befindet sich das Dokument (oder der Schatten-DOM) nicht im Vollbildmodus.

Document.fullscreenEnabled

Die Eigenschaft fullscreenEnabled teilt Ihnen mit, ob das Dokument sich derzeit in einem Zustand befindet, der das Anfordern des Vollbildmodus ermöglichen würde.

Einige mobile Browser ignorieren im Vollbildmodus die Einstellungen des Viewport-Meta-Tags und blockieren die Benutzervergrößerung; ein "Pinch-to-Zoom"-Gestus funktioniert möglicherweise auf einer im Vollbildmodus angezeigten Seite nicht - selbst wenn die Seite, wenn sie nicht im Vollbildmodus ist, mit Pinch-to-Zoom skaliert werden kann.

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

Darüber hinaus führt das Navigieren zu einer anderen Seite, das Wechseln von Tabs oder das Umschalten zu einer anderen Anwendung (z.B. mit 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 umschalten.

Beispiele live ansehen

Wenn die Seite geladen wird, wird dieser Code ausgeführt, um einen Event-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 die Enter-Taste drückt, wie oben gesehen.

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

Dies beginnt mit dem Überprüfen des Werts des fullscreenElement-Attributs auf dem 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 Aufrufen von Element.requestFullscreen().

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

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