Element: requestFullscreen() Methode

Syntax

requestFullscreen()
requestFullscreen(options)

Parameter

options Optional

Ein Objekt, das das Verhalten des Wechsels zum Vollbildmodus steuert. Die verfügbaren Optionen sind:

navigationUI Optional

Steuert, ob die Navigations-Benutzeroberfläche angezeigt werden soll, 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 Abmessungen des Bildschirms werden zur Anzeige des Elements genutzt.

"show"

Der Browser zeigt Seitennavigationskontrollen und möglicherweise andere Benutzeroberflächen an; die Abmessungen des Elements (und die wahrgenommene Größe des Bildschirms) werden eingeschränkt, um Platz für diese Benutzeroberfläche zu lassen.

"auto"

Der Browser wählt aus, welche der obigen Einstellungen angewendet wird. Dies ist der Standardwert.

screen Optional Experimentell

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

Rückgabewert

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

Ausnahmen

Anstelle einer herkömmlichen Ausnahme wirft das requestFullscreen()-Verfahren bei Fehlerbedingungen keine „Throw“-Ausnahme, sondern lehnt das zurückgegebene Promise ab. Der Ablehnungs-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 befindet sich nicht in einem Dokument.
• Dem Element ist es nicht gestattet, das fullscreen-Feature zu verwenden, entweder aufgrund von 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.

Sicherheit

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

Verwendungshinweise

Kompatible Elemente

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

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

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

Erkennung der Vollbildaktivierung

Sie können feststellen, ob Ihr Versuch, in den Vollbildmodus zu wechseln, erfolgreich war, indem Sie das zurückgegebene Promise von requestFullscreen() 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 zu wissen, wann beispielsweise der Benutzer den Vollbildmodus manuell umschaltet oder Anwendungen wechselt, wodurch Ihre Anwendung vorübergehend den Vollbildmodus verlässt.

Beispiele

Anfordern des Vollbildmodus

Dieses Beispiel schaltet das <video>-Element in den Vollbildmodus um, 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 den Modus 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: #444488;
}
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;
}

Verwendung von navigationUI

In diesem Beispiel wird das gesamte Dokument in den Vollbildmodus versetzt, indem requestFullscreen() auf das 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 Auflösungs-Handler des Promises macht nichts, aber wenn das Promise abgelehnt wird, wird eine Fehlermeldung durch Aufruf von alert() angezeigt.

Verwendung der Bildschirmoption

Wenn Sie das Element auf dem primären Betriebssystembildschirm im Vollbildmodus darstellen 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 Window.getScreenDetails()-Methode wird verwendet, um das ScreenDetails-Objekt für das aktuelle Gerät abzurufen, das ScreenDetailed-Objekte enthält, die die verschiedenen verfügbaren Bildschirme darstellen.

Spezifikationen

Browser-Kompatibilität

Siehe auch

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