Element: requestFullscreen() Methode

options Optional

Ein Objekt, das das Verhalten des Übergangs in den Vollbildmodus steuert. Die verfügbaren Optionen sind:

navigationUI Optional

Bestimmt, ob die Navigation UI angezeigt wird, während das Element im Vollbildmodus ist. Der Standardwert ist "auto", was bedeutet, dass der Browser entscheiden soll, was zu tun ist.

"hide"

Die Navigationsoberfläche des Browsers wird ausgeblendet und die gesamten Bildschirmdimensionen werden zur Anzeige des Elements verwendet.

"show"

Der Browser wird Seitennavigationssteuerungen und möglicherweise andere Benutzeroberflächen präsentieren; die Dimensionen des Elements (und die wahrgenommene Größe des Bildschirms) werden begrenzt, um Platz für diese Benutzeroberfläche zu lassen.

"auto"

Der Browser wählt, welche der obigen Einstellungen anzuwenden ist. Dies ist der Standardwert.

screen Optional Experimentell

Gibt an, auf welchem Bildschirm Sie das Element im Vollbildmodus anzeigen möchten. Dies nimmt ein ScreenDetailed Objekt als Wert, das den gewählten Bildschirm darstellt.

Ein Promise, das mit einem Wert von undefined aufgelöst wird, wenn der Übergang zum Vollbildmodus abgeschlossen ist.

Anstatt eine traditionelle Ausnahme auszuwerfen, gibt das requestFullscreen()-Verfahren Fehlerbedingungen durch das Ablehnen des zurückgegebenen Promise bekannt. Der Rejection-Handler erhält einen der folgenden Ausnahme-Werte:

TypeError

Die TypeError-Ausnahme kann in einer der folgenden Situationen auftreten:

• Das Dokument, das das Element enthält, ist nicht vollständig aktiv; das heißt, es ist nicht das derzeit aktive Dokument.
• Das Element wird nicht von einem Dokument enthalten.
• Dem Element ist es nicht gestattet, das fullscreen-Feature zu verwenden, entweder aufgrund der Permissions Policy-Konfiguration oder anderer Zugriffskontrollfunktionen.
• Das Element und sein Dokument sind derselbe Knoten.
• Das Element ist ein Popover, das bereits über HTMLElement.showPopover() angezeigt wird.

Vorübergehende Benutzeraktivierung ist erforderlich. Der Benutzer muss mit der Seite oder einem UI-Element interagieren, damit diese Funktion funktioniert.

Ein Element, das Sie im Vollbildmodus anzeigen möchten, muss einige einfache Anforderungen erfüllen:

• Es muss eines der Standard-HTML-Elemente sein oder <svg> oder <math>.
• Es ist kein <dialog> Element.
• Es muss sich entweder im obersten Dokument befinden oder in einem <iframe>, bei dem das Attribut allowfullscreen angewendet wurde.

Zusätzlich müssen alle festgelegten Berechtigungsrichtlinien die Verwendung dieser Funktion erlauben.

Sie können feststellen, ob Ihr Versuch, in den Vollbildmodus zu wechseln, erfolgreich ist, indem Sie das Promise, das von requestFullscreen() zurückgegeben wird, verwenden, wie in den Beispielen unten gezeigt.

Um zu erfahren, wann anderer Code den Vollbildmodus ein- und ausschaltet, sollten Sie Listener für das fullscreenchange Ereignis im Document einrichten. Es ist auch wichtig, auf fullscreenchange zu hören, um informiert zu bleiben, wenn beispielsweise der Benutzer den Vollbildmodus manuell umschaltet oder wenn der Benutzer Anwendungen wechselt, was dazu führt, dass Ihre Anwendung vorübergehend den Vollbildmodus verlässt.

Diese Funktion schaltet das erste im Dokument gefundene <video> Element in und aus dem Vollbildmodus um.

function toggleFullscreen() {
  let elem = document.querySelector("video");

  if (!document.fullscreenElement) {
    elem.requestFullscreen().catch((err) => {
      alert(
        `Error attempting to enable fullscreen mode: ${err.message} (${err.name})`,
      );
    });
  } else {
    document.exitFullscreen();
  }
}

Wenn sich das Dokument noch nicht im Vollbildmodus befindet – erkannt, indem überprüft wird, ob document.fullscreenElement einen Wert hat – rufen wir die requestFullscreen() Methode des Videos auf. Wir brauchen nichts Besonderes zu tun, wenn es erfolgreich ist, aber wenn die Anfrage fehlschlägt, zeigt der catch()-Handler unseres Promises einen Alarm mit einer entsprechenden Fehlermeldung an.

Wenn andererseits der Vollbildmodus bereits aktiv ist, rufen wir document.exitFullscreen() auf, um den Vollbildmodus zu deaktivieren.

Sie können dieses Beispiel in Aktion sehen oder den Code anzeigen oder remixen auf Glitch.

In diesem Beispiel wird das gesamte Dokument in den Vollbildmodus versetzt, indem requestFullscreen() auf dem Document.documentElement des Dokuments aufgerufen wird, das das Wurzel-<html>-Element des Dokuments ist.

let elem = document.documentElement;

elem
  .requestFullscreen({ navigationUI: "show" })
  .then(() => {})
  .catch((err) => {
    alert(
      `An error occurred while trying to switch into fullscreen mode: ${err.message} (${err.name})`,
    );
  });

Der Resolve-Handler des Promises tut nichts, aber wenn das Promise abgelehnt wird, wird eine Fehlermeldung angezeigt, indem alert() aufgerufen wird.

Wenn Sie das Element auf dem primären Betriebssystembildschirm im Vollbildmodus anzeigen möchten, könnten Sie Code wie den folgenden verwenden:

try {
  const primaryScreen = (await getScreenDetails()).screens.find(
    (screen) => screen.isPrimary,
  );
  await document.body.requestFullscreen({ screen: primaryScreen });
} catch (err) {
  console.error(err.name, err.message);
}

Die Methode Window.getScreenDetails() wird verwendet, um das ScreenDetails Objekt für das aktuelle Gerät abzurufen, das ScreenDetailed Objekte für die verschiedenen verfügbaren Bildschirme enthält.

• Fullscreen API
• Document.exitFullscreen()
• Document.fullscreen
• Document.fullscreenElement
• :fullscreen
• allowfullscreen