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 Navigations-Benutzeroberfläche während des Vollbildmodus angezeigt werden soll. 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 Abmessungen des Bildschirms werden für die Anzeige des Elements verwendet.

"show"

Der Browser präsentiert Seiten-Navigationselemente und möglicherweise andere Benutzeroberflächen; die Maße des Elements (und die wahrgenommene Größe des Bildschirms) werden angepasst, um Platz für diese Benutzeroberfläche zu lassen.

"auto"

Der Browser wählt aus, welche der oben genannten Einstellungen angewendet werden soll. Dies ist der Standardwert.

screen Optional Experimentell

Gibt an, auf welchem Bildschirm das Element im Vollbildmodus angezeigt werden soll. Dies nimmt ein ScreenDetailed Objekt als Wert, das den gewählten Bildschirm darstellt.

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

Anstatt eine traditionelle Ausnahme zu werfen, meldet das requestFullscreen() Verfahren Fehlerbedingungen, indem es das zurückgegebene Promise ablehnt. Der Ablehnungshandler 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 vollständig aktiv; das heißt, es ist nicht das aktuelle aktive Dokument.
• Das Element gehört zu keinem Dokument.
• Dem Element ist es nicht erlaubt, die fullscreen Funktion zu verwenden, entweder aufgrund der Permissions Policy Konfiguration oder anderer Zugriffskontrollfunktionen.
• Das Element und sein Dokument sind ein und dasselbe Knoten.
• Das Element ist ein popover, das bereits über HTMLElement.showPopover() angezeigt wird.

Flüchtige 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 eine kleine Anzahl einfacher Anforderungen erfüllen:

• Es muss eines der Standard-HTML-Elemente oder <svg> oder <math> sein.
• Es ist nicht ein <dialog> Element.
• Es muss entweder im obersten Dokument oder in einem <iframe> liegen, das das allowfullscreen Attribut angewendet 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 von requestFullscreen() zurückgegebene Promise verwenden, wie in den Beispielen unten gezeigt.

Um zu erfahren, wann anderer Code den Vollbildmodus umgeschaltet hat, sollten Sie Listener für das fullscreenchange Ereignis auf dem Document einrichten. Es ist auch wichtig, auf fullscreenchange zu hören, um informiert zu bleiben, wenn zum Beispiel der Benutzer den Vollbildmodus manuell umschaltet oder wenn der Benutzer die Anwendungen wechselt, wodurch Ihre Anwendung vorübergehend den Vollbildmodus verlässt.

Diese Funktion schaltet das erste <video> Element im Dokument in den Vollbildmodus und 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 sich das Dokument noch nicht im Vollbildmodus befindet – festgestellt durch Überprüfen, 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 bereits der Vollbildmodus 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 Document.documentElement aufgerufen wird, das das Stamm-<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 Promise macht nichts, aber wenn das Promise abgelehnt wird, wird eine Fehlermeldung angezeigt, indem alert() aufgerufen wird.

Wenn Sie das Element im Vollbildmodus auf dem primären Betriebssystembildschirm anzeigen wollten, 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 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