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-UI während des Vollbildmodus des Elements angezeigt wird oder nicht. Der Standardwert ist "auto", was bedeutet, dass der Browser entscheiden soll, was zu tun ist.

"hide"

Die Navigationsoberfläche des Browsers wird verborgen, und die gesamten Bildschirmabmessungen werden zur Anzeige des Elements genutzt.

"show"

Der Browser zeigt Navigationssteuerungen der Seite und möglicherweise andere Benutzeroberflächen an; die Abmessungen des Elements (und die wahrgenommene Bildschirmgröße) werden begrenzt, um Platz für diese Benutzeroberfläche zu lassen.

"auto"

Der Browser wählt, 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 repräsentiert.

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

Anstatt eine herkömmliche Ausnahme auszuwerfen, kündigt das requestFullscreen()-Verfahren Fehlerbedingungen an, indem das zurückgegebene Promise abgelehnt wird. Der Ablehnungshandler erhält einen der folgenden Ausnahmewerte:

TypeError

Die TypeError-Ausnahme kann in einer der folgenden Situationen ausgeliefert werden:

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

Ein vorübergehender Benutzeraktivierungszustand ist erforderlich. Der Benutzer muss mit der Seite oder einem UI-Element interagieren, damit diese Funktion arbeitet.

Ein Element, das Sie in den Vollbildmodus schalten möchten, muss eine kleine Anzahl einfacher 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 obersten Dokuments platziert sein oder in einem <iframe>, das das allowfullscreen-Attribut hat.

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

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

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, fullscreenchange zu überwachen, um sich darüber im Klaren zu sein, wenn der Benutzer beispielsweise manuell den Vollbildmodus umschaltet oder die Anwendung wechselt, was dazu führt, dass Ihre Anwendung vorübergehend den Vollbildmodus verlässt.

Diese Funktion schaltet das erste <video>-Element im Dokument in den Vollbildmodus und wieder zurück.

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 das Dokument nicht bereits im Vollbildmodus ist – was erkannt wird, indem überprüft wird, ob document.fullscreenElement einen Wert hat – rufen wir die requestFullscreen()-Methode des Videos auf. Wir müssen nichts Besonderes tun, wenn es erfolgreich ist, aber wenn die Anfrage fehlschlägt, zeigt der catch()-Handler unseres Promises eine Warnung mit einer entsprechenden Fehlermeldung an.

Wenn hingegen 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 ansehen oder bearbeiten auf Glitch.

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

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 Auflösungs-Handler des Promises macht nichts, aber wenn das Promise abgelehnt wird, wird eine Fehlermeldung angezeigt, indem alert() aufgerufen wird.

Wenn Sie das Element auf dem primären Betriebssystem-Bildschirm im Vollbildmodus anzeigen möchten, könnten Sie einen 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 enthält, welche die verschiedenen verfügbaren Bildschirme darstellen.

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