Element: requestFullscreen() Methode

Limited availability

This feature is not Baseline because it does not work in some of the most widely-used browsers.

Die Element.requestFullscreen()-Methode sendet eine asynchrone Anfrage, um das Element im Vollbildmodus anzuzeigen.

Es ist nicht garantiert, dass das Element in den Vollbildmodus geschaltet wird. Wenn die Erlaubnis erteilt wird, den Vollbildmodus zu betreten, wird das zurückgegebene Promise aufgelöst und das Element erhält ein fullscreenchange-Ereignis, um anzuzeigen, dass es sich jetzt im Vollbildmodus befindet. Wenn die Erlaubnis verweigert wird, wird das Versprechen abgelehnt und das Element erhält stattdessen ein fullscreenerror-Ereignis. Wenn das Element aus dem ursprünglichen Dokument entfernt wurde, erhält das Dokument stattdessen diese Ereignisse.

Syntax

js
requestFullscreen()
requestFullscreen(options)

Parameter

options Optional

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

Bestimmt, ob die Navigationsbenutzeroberfläche angezeigt werden soll, während sich das Element im Vollbildmodus befindet. Der Standardwert ist "auto", was bedeutet, dass der Browser entscheiden sollte, was zu tun ist.

"hide"

Die Navigationsoberfläche des Browsers wird ausgeblendet und die gesamten Dimensionen des Bildschirms werden zur Anzeige des Elements verwendet.

"show"

Der Browser präsentiert Seitennavigationselemente und möglicherweise andere Benutzeroberflächen; die Abmessungen des Elements (und die wahrgenommene Größe des Bildschirms) werden gekürzt, 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 das Element im Vollbildmodus angezeigt werden soll. Dies nimmt ein ScreenDetailed-Objekt als Wert, das den gewählten Bildschirm darstellt.

Rückgabewert

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

Ausnahmen

Anstatt eine herkömmliche Ausnahme auszulösen, kündigt die requestFullscreen()-Prozedur Fehlerbedingungen durch Ablehnen des zurückgegebenen Promise an. 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 aktuell aktive Dokument.
  • Das Element ist nicht in einem Dokument enthalten.
  • Das Element darf die fullscreen-Funktion nicht nutzen, entweder aufgrund 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.

Sicherheit

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

Verwendungshinweise

Kompatible Elemente

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 ein <svg>- oder <math>-Element sein.
  • Es ist kein <dialog>-Element.
  • Es muss sich entweder im obersten Dokument oder in einem <iframe> befinden, das das allowfullscreen-Attribut angewendet hat.

Zusätzlich müssen alle gesetzten Berechtigungsrichtlinien die Verwendung dieser Funktion erlauben.

Erkennung der Vollbildaktivierung

Sie können bestimmen, 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 ein- und ausgeschaltet hat, sollten Sie Listener für das fullscreenchange-Ereignis auf dem Document einrichten. Es ist auch wichtig, auf fullscreenchange zu hören, um zu wissen, wann der Benutzer manuell den Vollbildmodus umschaltet oder wann der Benutzer Anwendungen wechselt, sodass Ihre Anwendung vorübergehend den Vollbildmodus verlässt.

Beispiele

Anfordern des Vollbildmodus

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

js
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}`);
    });
  }
});
html
<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>

Verwenden von navigationUI

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

js
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ösungshandler des Versprechens unternimmt nichts, aber wenn das Versprechen abgelehnt wird, wird eine Fehlermeldung angezeigt, indem alert() aufgerufen wird.

Verwendung der Bildschirmoption

Wenn Sie das Element im Vollbildmodus auf dem primären Betriebssystembildschirm anzeigen möchten, können Sie etwa folgenden Code verwenden:

js
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.

Spezifikationen

Specification
Fullscreen API
# ref-for-dom-element-requestfullscreen①

Browser-Kompatibilität

Siehe auch