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 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 Navigationsschnittstelle des Browsers wird ausgeblendet und die gesamten Abmessungen des Bildschirms werden der Anzeige des Elements zugewiesen.

"show"

Der Browser präsentiert Seitennavigationselemente und möglicherweise andere Benutzeroberflächen; die Abmessungen 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, welche der oben genannten Einstellungen angewendet werden soll. 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 traditionelle Ausnahme zu werfen, meldet das requestFullscreen() Verfahren Fehlbedingungen, indem es das zurückgegebene Promise ablehnt. Der Ablehnungs-Handler erhält einen der folgenden Ausnahme-Werte:

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 ist nicht in 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.

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

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

Zusätzlich müssen alle gesetzten Berechtigungsrichtlinien die Verwendung dieses Features zulassen.

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 umschaltet, sollten Sie Listener für das fullscreenchange-Ereignis auf dem Document einrichten. Es ist auch wichtig, auf fullscreenchange zu achten, um informiert zu sein, wenn beispielsweise der Benutzer den Vollbildmodus manuell umschaltet oder wenn der Benutzer die Anwendung wechselt, wodurch Ihre Anwendung den Vollbildmodus vorübergehend verlässt.

Dieses Beispiel schaltet das <video>-Element in den Vollbildmodus und aus diesem heraus, wenn die Tasten Enter oder Shift + F gedrückt werden. Das Skript überprüft, ob das Dokument derzeit im Vollbildmodus ist, indem es document.fullscreenElement verwendet. Wenn das Dokument im Vollbildmodus ist, wird document.exitFullscreen() aufgerufen, um diesen zu verlassen. Andernfalls wird requestFullscreen() auf dem <video>-Element aufgerufen:

const video = document.querySelector("video");

document.addEventListener("keydown", (event) => {
  // Note that "F" is case-sensitive (uppercase):
  if (event.key === "Enter" || event.key === "F") {
    // Check if we're in fullscreen mode
    if (document.fullscreenElement) {
      document.exitFullscreen();
      return;
    }
    // Otherwise enter fullscreen mode
    video.requestFullscreen().catch((err) => {
      console.error(`Error enabling fullscreen: ${err.message}`);
    });
  }
});

<p>
  The video element below shows a time-lapse of a flower blooming. You can
  toggle fullscreen on and off using <kbd>Enter</kbd> or <kbd>Shift</kbd> +
  <kbd>F</kbd> (uppercase "F"). The embedded document needs to have
  <a
    href="https://developer.mozilla.org/en-US/docs/Web/API/Element/focus_event">
    focus
  </a>
  for the example to work.
</p>

<video controls loop src="/shared-assets/videos/flower.mp4" width="420"></video>

body {
  font-family: "Benton Sans", "Helvetica Neue", helvetica, arial, sans-serif;
  margin: 2em;
}

video::backdrop {
  background-color: #448;
}
button {
  display: block;
}
kbd {
  border: 2px solid #cdcdcd;
  border-radius: 3px;
  box-shadow: inset 0 -1px 0 0 #cdcdcd;
  font-size: 0.825rem;
  padding: 0.25rem;
}

In diesem Beispiel wird das gesamte Dokument durch Aufruf von requestFullscreen() auf dem Document.documentElement des Dokuments in den Vollbildmodus versetzt, das das Wurzelelement des Dokuments <html> 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 macht nichts, aber wenn das Promise abgelehnt wird, wird eine Fehlermeldung angezeigt, indem alert() aufgerufen wird.

Wenn Sie das Element auf dem primären OS-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 repräsentiert, die die verschiedenen verfügbaren Bildschirme darstellen.

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