Element: requestFullscreen() Methode

Syntax

requestFullscreen()
requestFullscreen(options)

Parameter

options Optional

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

keyboardLock Optional

Steuert den ausgewählten Keyboard-Lock-Modus.

"none"

Es wird kein Keyboard-Lock angewendet. Dies ist der Standardmodus.

"browser"

Der Browser-Keyboard-Lock-Modus wird angewendet. In diesem Modus leitet der Browser Tastenereignisse an die Anwendung weiter, die normalerweise vom Browser- oder Systemcode verarbeitet würden. Anwendungen sollten Ereignisse für die Tasten und Tastenkombinationen abfangen, die sie verwenden möchten, und preventDefault() aufrufen, um alle Standardaktionen zu unterbrechen.

Beachten Sie, dass einige Browser die Standardaktion für einige Tasten deaktivieren können, z.B. die Taste, die normalerweise verwendet wird, um den Vollbildmodus zu beenden; dies ist nicht garantiert, daher sollten Sie immer preventDefault() aufrufen. Browser werden auch dazu angehalten, einen Mechanismus bereitzustellen, um den Vollbildmodus mit Keyboard-Lock zu beenden.

Weitere Informationen finden Sie im Abschnitt Keyboard-Locking unten.

navigationUI Optional

Steuert, ob die Navigations-Benutzeroberfläche angezeigt wird, während sich das Element im Vollbildmodus befindet. Der Standardwert ist "auto", was bedeutet, dass der Browser entscheidet, was zu tun ist.

"hide"

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

"show"

Der Browser zeigt Seiten-Navigationssteuerungen und möglicherweise andere Benutzeroberflächen an; 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 obigen Einstellungen angewendet werden soll. Dies ist der Standardwert.

screen Optional

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

Rückgabewert

Ein Promise, das mit einem Wert von undefined aufgelöst wird, wenn der Übergang zum Vollbild abgeschlossen ist, oder mit einer Ausnahme zurückgewiesen wird.

Ausnahmen

Bei einem Fehler lehnt das zurückgegebene Promise mit einem der folgenden Werte ab:

TypeError

Die Ausnahme TypeError kann in einer der folgenden Situationen ausgegeben 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 nicht gestattet, die fullscreen-Funktion zu verwenden, entweder wegen 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.

NotSupportedError DOMException

Der übergebene options.keyboardLock-Parameter wird vom Browser nicht unterstützt.

Beschreibung

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

Die Methode erfordert eine Erlaubnis.

• Wenn die Erlaubnis zum Betreten des Vollbildmodus erteilt wird, wird das zurückgegebene Promise aufgelöst und das Element erhält ein fullscreenchange Ereignis, um zu wissen, dass es sich jetzt im Vollbildmodus befindet.
• Wenn die Erlaubnis verweigert wird, wird das Promise zurückgewiesen und das Element erhält stattdessen ein fullscreenerror Ereignis.

Wenn das Element vom ursprünglichen Dokument getrennt wurde, erhält stattdessen das Dokument diese Ereignisse.

Kompatible Elemente

Ein Element, das Sie im Vollbildmodus anzeigen 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 sich entweder im obersten Dokument befinden oder in einem <iframe>, dem das allowfullscreen Attribut zugewiesen ist.

Zusätzlich muss jede gesetzte Permissions-Policy die Nutzung der fullscreen-Funktion erlauben.

Erkennung der Vollbildaktivierung

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 festzustellen, wann anderer Code den Vollbildmodus ein- und ausschaltet, sollten Sie Zuhörer für das fullscreenchange Ereignis am Document einrichten. Es ist auch wichtig, fullscreenchange zu überwachen, um zu wissen, wann z.B. der Benutzer den Vollbildmodus manuell umschaltet oder wenn der Benutzer die Anwendung wechselt, was dazu führt, dass Ihre Anwendung vorübergehend den Vollbildmodus verlässt.

Keyboard-Locking

Keyboard-Locking ermöglicht es einer Vollbildanwendung, einige Tasten und Tastenkombinationen abzufangen und zu behandeln, die ansonsten ausschließlich vom Browser oder dem darunterliegenden Betriebssystem verarbeitet würden. Dies kann die Benutzererfahrung für Spiele verbessern, indem beispielsweise die Esc-Taste als Menütaste verwendet werden kann, anstatt den Vollbildmodus zu verlassen. Es kann auch für Anwendungen wie Remote-Desktop-Steuerung nützlich sein, bei denen nahezu alle Tastaturereignisse an den entfernten Computer weitergeleitet werden sollen.

Der Tastatursperre wird aktiviert, indem beim Aktivieren des Vollbildmodus der Wert "browser" an den options.keyboardLock Parameter übergeben wird. Wenn die Tastatursperre im Vollbildmodus aktiv ist, leitet der Browser "viel mehr" Tastaturereignisse an die Anwendung weiter – das genaue Set an Tasten ist browserabhängig. Die Webanwendung sollte das Ereignis abfangen, indem sie zuerst preventDefault() aufruft, um die Standardaktion abzubrechen. Einige Tastenkombinationen werden für Systemsteuerungen verwendet oder haben Datenschutzrisiken und können daher nicht mit diesem Mechanismus abgefangen und deaktiviert werden (zum Beispiel Ctrl+Alt+Delete unter Windows).

Beachten Sie, dass einige Browser im Tastatursperrenmodus immer die Standardaktion der Esc-Taste deaktivieren, sodass das Drücken dieser nicht automatisch den Vollbildmodus beendet. Da dies jedoch nicht garantiert ist, müssen Sie dennoch preventDefault() aufrufen, um zu verhindern, dass Esc-Tastendrücke den Vollbildmodus beenden. Allgemeiner gilt, dass Sie nicht davon ausgehen können, dass die Standardaktion für ein Tastaturereignis standardmäßig deaktiviert ist.

Es wird erwartet, dass Browser einen alternativen Mechanismus zum Beenden des Vollbildmodus bereitstellen, wenn die Tastatursperre aktiviert ist. Die meisten Browser verwenden die Esc-Taste, um den normalen Vollbildmodus zu beenden, und eine lange gedrückte Esc-Taste, um den Tastatursperre zu beenden. Der Tastatursperre wird deaktiviert, wenn der Browser den Vollbildmodus verlässt.

Sicherheitsaspekte

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

Der Vollbildmodus wird durch die Permissions-Policy Direktive fullscreen gesteuert.

Die Standard-Zulassungsliste für screen-wake-lock ist self. Dies erlaubt die Verwendung des Vollbildmodus in gleichnamigen verschachtelten Frames, verhindert jedoch dessen Einsatz in Inhalten von Drittanbietern. Die Nutzung durch Dritte kann aktiviert werden, indem der Server zuerst den Permissions-Policy-Header so setzt, dass er einer bestimmten Drittanbieter-Origin die Erlaubnis erteilt.

Permissions-Policy: fullscreen=(self b.example.com)

Dann muss das allow="fullscreen" Attribut dem Rahmencontainer-Element für Quellen von diesem Ursprung hinzugefügt werden:

<iframe src="https://b.example.com" allow="fullscreen"></iframe>

Die Permissions API fullscreen Erlaubnis kann verwendet werden, um zu testen, ob der Zugriff auf den Modus als granted, denied oder prompt (benötigt Benutzerbestätigung einer Aufforderung) eingestuft wird.

Beispiele

Anfordern des Vollbildmodus

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

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://www.supremezsy.dpdns.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;
}

Verwenden der Tastatursperre

Dieses Beispiel ist fast dasselbe wie das vorherige Beispiel, außer dass wir anfordern, dass der Vollbildmodus mit Tastatursperre geöffnet wird.

JavaScript

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

Der geänderte Tastenereignis-Listener-Code ist unten gezeigt.

Der erste Unterschied besteht darin, dass wir das Ereignis für die Esc-Taste im Vollbildmodus behandeln und event.preventDefault() aufrufen, um die Standardaktion zu deaktivieren (die darin bestehen würde, den Vollbildmodus zu beenden).

Wie zuvor rufen wir requestFullscreen() auf, wenn Enter oder Shift+F gedrückt werden, wenn sich das Dokument nicht im Vollbildmodus befindet. In diesem Fall übergeben wir jedoch die keyboardLock-Option mit dem Wert "browser".

document.addEventListener("keydown", (event) => {
  // Check if we're in fullscreen mode
  if (document.fullscreenElement) {
    // Cancel exiting via the Escape key
    if (event.key === "Escape") {
      event.preventDefault();
      // Do whatever else you might want to do when escape is pressed
    }
  } else {
    // Open full screen if Enter or F is pressed.
    // Note that "F" is case-sensitive (uppercase):
    if (event.key === "Enter" || event.key === "F") {
      // Otherwise enter fullscreen mode
      video.requestFullscreen({ keyboardLock: "browser" }).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+F</kbd> (uppercase "F"). The embedded document needs to have
  <a
    href="https://www.supremezsy.dpdns.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;
}

Ergebnisse

Wählen Sie den Frame aus und drücken Sie Shift+F. Wenn die Seite den Vollbildrahmen anzeigt, beachten Sie die vorübergehende Benachrichtigung oben auf der Seite, die erklärt, wie Sie den Vollbildmodus beenden können.

Verwenden des navigationUI

In diesem Beispiel wird das gesamte Dokument in den Vollbildmodus versetzt, indem requestFullscreen() auf dem 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 Resolve-Handler des Promise macht nichts, aber wenn das Promise zurückgewiesen wird, wird eine Fehlermeldung durch Aufrufen von alert() angezeigt.

Verwenden der Bildschirme-Option

Wenn Sie das Element auf dem primären Betriebssystembildschirm im Vollbildmodus anzeigen möchten, könnten Sie solch einen Code 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, welches 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