Element: requestFullscreen() Methode

options Optional

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

navigationUI Optional

Steuert, ob die Navigations-Benutzeroberfläche angezeigt werden soll, während sich das Element im Vollbildmodus befindet. Der Standardwert ist "auto", was anzeigt, dass der Browser entscheiden sollte, was zu tun ist.

"hide"

Die Navigationsoberfläche des Browsers wird versteckt und der gesamte Bildschirm wird für die Anzeige des Elements genutzt.

"show"

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

"auto"

Der Browser wird wählen, welche der oben genannten Einstellungen angewendet wird. 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 an, das den ausgewählten Bildschirm darstellt.

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

Anstatt eine traditionelle Ausnahme auszulösen, kündigt der requestFullscreen()-Prozess Fehlerbedingungen an, indem das Promise, das zurückgegeben wird, abgelehnt wird. Der Ablehnungs-Handler erhält einen der folgenden Ausnahmewerte:

TypeError

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

• Das Dokument, das das Element enthält, ist nicht voll aktiv; das heißt, es ist nicht das aktuell aktive Dokument.
• Das Element ist nicht in einem Dokument enthalten.
• Dem Element ist die Nutzung der fullscreen-Funktion nicht gestattet, entweder wegen der Permissions Policy Konfiguration oder anderer Zugriffskontrollfunktionen.
• Das Element und sein Dokument sind der gleiche Knoten.
• Das Element ist ein Popover, das bereits über HTMLElement.showPopover() angezeigt wird.

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

Ein Element, das Sie in den Vollbildmodus versetzen möchten, muss einige einfache Anforderungen erfüllen:

• Es muss eines der standardmäßigen HTML-Elemente oder <svg> oder <math> sein.
• Es ist kein <dialog> Element.
• Es muss entweder innerhalb des Hauptdokuments oder in einem <iframe> sein, das das allowfullscreen Attribut angewendet hat.

Darüber hinaus müssen alle festgelegten Berechtigungsrichtlinien die Verwendung dieser Funktion ermöglichen.

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

Um zu erfahren, wann anderer Code den Vollbildmodus ein- und ausblendet, sollten Sie Zuhörer für das fullscreenchange Ereignis im Document einrichten. Es ist auch wichtig, fullscreenchange zu überwachen, um zu erfahren, wenn beispielsweise der Benutzer den Vollbildmodus manuell umschaltet oder die Anwendung wechselt, wodurch Ihre Anwendung vorübergehend den Vollbildmodus verlässt.

Diese Funktion schaltet das erste im Dokument gefundene <video> Element in den 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 nicht bereits im Vollbildmodus befindet – erkannt durch das Prüfen, ob document.fullscreenElement einen Wert hat – rufen wir die requestFullscreen()-Methode des Videos auf. Wenn wir erfolgreich sind, müssen wir nichts Besonderes tun. Wenn die Anfrage fehlschlägt, präsentiert der catch()-Handler unseres Versprechens eine Warnung mit einer entsprechenden Fehlermeldung.

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

Sie können dieses Beispiel in Aktion sehen oder den Code ansehen 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, welches 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 Resolver des Versprechens tut nichts, aber wenn das Versprechen abgelehnt wird, wird eine Fehlermeldung über das Aufrufen von alert() angezeigt.

Wenn Sie das Element auf dem primären OS-Bildschirm im Vollbildmodus anzeigen möchten, könnten Sie folgenden Code 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 Window.getScreenDetails() Methode wird verwendet, um das ScreenDetails Objekt für das aktuelle Gerät abzurufen, das ScreenDetailed Objekte darstellt, die die verschiedenen verfügbaren Bildschirme repräsentieren.

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