Element: requestFullscreen() method

Syntax

requestFullscreen()
requestFullscreen(options)

Parameter

options Optional

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

keyboardLock Optional

Steuert den ausgewählten Tastatursperrmodus.

"none"

Es wird keine Tastatursperre angewendet. Dies ist der Standardmodus.

"browser"

Der Tastatursperrmodus des Browsers wird angewendet. In diesem Modus leitet der Browser Tastaturereignisse an die Anwendung weiter, die normalerweise durch 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 Standardaktionen abzubrechen.

Beachten Sie, dass einige Browser die Standardaktion für bestimmte Tasten deaktivieren können, etwa für die Taste, die normalerweise zum Verlassen des Vollbildmodus verwendet wird; dies ist nicht garantiert, daher sollten Sie immer preventDefault() aufrufen. Browser werden außerdem dazu angehalten, einen Mechanismus zum Verlassen des Vollbildmodus mit Tastatursperre bereitzustellen.

Weitere Informationen finden Sie im Abschnitt Tastatursperre weiter unten.

navigationUI Optional

Steuert, ob die Navigations-Benutzeroberfläche angezeigt wird, während sich das Element im Vollbildmodus befindet. Der Standardwert ist "auto", was angibt, 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 zeigt Steuerelemente zur Seitennavigation und möglicherweise weitere Benutzeroberflächenelemente an; die Abmessungen des Elements (und die wahrgenommene Größe des Bildschirms) werden begrenzt, um Platz für diese Benutzeroberfläche zu lassen.

"auto"

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

screen Optional

Gibt an, auf welchem Bildschirm Sie das Element im Vollbildmodus anzeigen möchten. Als Wert wird ein ScreenDetailed-Objekt verwendet, das den ausgewählten Bildschirm darstellt.

Rückgabewert

Ein Promise, das mit dem Wert undefined erfüllt wird, wenn der Übergang in den Vollbildmodus abgeschlossen ist, oder mit einer Ausnahme abgelehnt wird.

Ausnahmen

Bei einem Fehler wird das zurückgegebene Promise mit einem der folgenden Werte abgelehnt:

TypeError

Die Ausnahme TypeError kann in jeder der folgenden Situationen ausgelöst werden:

• Das Dokument, das das Element enthält, ist nicht vollständig aktiv; das heißt, es ist nicht das derzeit aktive Dokument.
• Das Element ist nicht in einem Dokument enthalten.
• Das Element darf die Funktion fullscreen nicht verwenden, entweder aufgrund einer Konfiguration der Permissions Policy 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 Parameter options.keyboardLock wird vom Browser nicht unterstützt.

Beschreibung

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

Die Methode erfordert eine Berechtigung.

• Wenn die Berechtigung zum Wechsel in den Vollbildmodus erteilt wird, wird das zurückgegebene Promise erfüllt und das Element erhält ein fullscreenchange-Ereignis, das ihm mitteilt, dass es sich nun im Vollbildmodus befindet.
• Wenn die Berechtigung verweigert wird, wird das Promise abgelehnt 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 in den Vollbildmodus versetzen möchten, muss eine kleine Anzahl einfacher Anforderungen erfüllen:

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

Zusätzlich muss jede festgelegte Permissions-Policy die Verwendung der Funktion fullscreen erlauben.

Erkennen der Vollbildaktivierung

Sie können anhand des von requestFullscreen() zurückgegebenen Promise feststellen, ob Ihr Versuch, in den Vollbildmodus zu wechseln, erfolgreich ist, wie in den folgenden Beispielen gezeigt.

Um zu erfahren, wann anderer Code den Vollbildmodus ein- oder ausgeschaltet hat, sollten Sie Listener für das Ereignis fullscreenchange auf dem Document einrichten. Es ist auch wichtig, auf fullscreenchange zu lauschen, um beispielsweise zu erkennen, wenn der Benutzer den Vollbildmodus manuell umschaltet oder wenn der Benutzer Anwendungen wechselt, wodurch Ihre Anwendung den Vollbildmodus vorübergehend verlässt.

Tastatursperre

Die Tastatursperre ermöglicht es einer Vollbildanwendung, bestimmte Tasten und Tastenkombinationen abzufangen und zu verarbeiten, die andernfalls ausschließlich vom Browser oder dem zugrunde liegenden Betriebssystem verarbeitet würden. Dies kann beispielsweise die Benutzererfahrung bei Spielen verbessern, indem die Taste Esc als Menütaste verwendet werden kann, anstatt den Vollbildmodus zu verlassen. Sie kann auch für Anwendungen wie die Fernsteuerung eines Desktops nützlich sein, bei denen Sie möchten, dass fast alle Tastenereignisse an den Remotecomputer weitergeleitet werden.

Die Tastatursperre wird aktiviert, indem beim Aktivieren des Vollbildmodus ein Tastatursperrmoduswert von "browser" an den Parameter options.keyboardLock übergeben wird. Wenn die Tastatursperre im Vollbildmodus aktiv ist, leitet der Browser „viel mehr“ Tastaturereignisse an die Anwendung weiter – die genaue Menge der Tasten ist browserabhängig. Die Webanwendung sollte das Ereignis verarbeiten, indem sie zunächst preventDefault() aufruft, um seine Standardaktion abzubrechen. Einige Tastenkombinationen werden zur Systemsteuerung verwendet oder bergen Datenschutzrisiken und können daher mit diesem Mechanismus nicht abgefangen und deaktiviert werden (zum Beispiel Ctrl+Alt+Delete unter Windows).

Beachten Sie, dass einige Browser die Standardaktion für die Taste Esc bei aktiver Tastatursperre immer deaktivieren, sodass deren Drücken nicht automatisch den Vollbildmodus verlässt. Da dies jedoch nicht garantiert ist, müssen Sie weiterhin preventDefault() aufrufen, um zu verhindern, dass das Drücken der Taste Esc den Vollbildmodus verlässt. Allgemeiner können Sie nicht davon ausgehen, dass die Standardaktion für ein Tastaturereignis standardmäßig deaktiviert ist.

Von Browsern wird erwartet, dass sie einen alternativen Mechanismus zum Verlassen des Vollbildmodus bereitstellen, wenn die Tastatursperre aktiviert ist. Die meisten Browser verwenden die Taste Esc, um den normalen Vollbildmodus zu verlassen, und ein langes Drücken der Taste Esc, um die Tastatursperre zu verlassen. Die Tastatursperre wird deaktiviert, wenn der Browser den Vollbildmodus verlässt.

Sicherheitsaspekte

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

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

Die Standard-Zulassungsliste für screen-wake-lock ist self. Dies erlaubt die Verwendung des Vollbildmodus in verschachtelten Frames derselben Origin, verhindert sie jedoch in Inhalten von Drittanbietern. Die Nutzung durch Drittanbieter kann aktiviert werden, indem der Server zunächst den Header Permissions-Policy setzt, um einer bestimmten Drittanbieter-Origin die Berechtigung zu erteilen.

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

Anschließend muss dem Frame-Containerelement für Quellen dieser Origin das Attribut allow="fullscreen" hinzugefügt werden:

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

Die Berechtigung fullscreen der Permissions API kann verwendet werden, um zu prüfen, ob der Zugriff zur Verwendung des Modus granted, denied oder prompt ist (erfordert die Bestätigung einer Aufforderung durch den Benutzer).

Beispiele

Vollbildmodus anfordern

Dieses Beispiel schaltet das <video>-Element in den und aus dem Vollbildmodus, wenn die Tasten Enter oder Shift + F gedrückt werden. Das Skript überprüft mithilfe von document.fullscreenElement, ob sich das Dokument derzeit im Vollbildmodus befindet. Wenn sich das Dokument im Vollbildmodus befindet, ruft es zum Beenden document.exitFullscreen() auf. Andernfalls ruft es requestFullscreen() für das <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://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;
}

Tastatursperre verwenden

Dieses Beispiel ist fast identisch mit dem vorherigen Beispiel, außer dass wir anfordern, den Vollbildmodus mit Tastatursperre zu öffnen.

JavaScript

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

Der geänderte Code für den Tastaturereignis-Listener wird unten gezeigt.

Der erste Unterschied besteht darin, dass wir das Ereignis für die Taste Esc im Vollbildmodus verarbeiten und event.preventDefault() aufrufen, um die Standardaktion zu deaktivieren (das wäre das Verlassen des Vollbildmodus).

Wie zuvor rufen wir requestFullscreen() auf, wenn Enter oder Shift+F gedrückt werden und der Vollbildmodus nicht aktiv ist. In diesem Fall übergeben wir jedoch die Option keyboardLock 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 if (event.key === "Enter" || event.key === "F") {
    // Open full screen if Enter or F is pressed and not already fullscreen.
    // Note that "F" is case-sensitive (uppercase).
    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://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;
}

Ergebnisse

Wählen Sie den Frame aus und drücken Sie Shift+F. Wenn die Seite als vollständiger Frame angezeigt wird, beachten Sie die temporäre Benachrichtigung oben auf der Seite, die erklärt, wie der Vollbildmodus verlassen werden kann.

navigationUI verwenden

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

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 führt keine Aktion aus, aber wenn das Promise abgelehnt wird, wird durch Aufruf von alert() eine Fehlermeldung angezeigt.

Die Option screen verwenden

Wenn Sie das Element auf dem primären Bildschirm des Betriebssystems im Vollbildmodus anzeigen möchten, könnten Sie folgenden 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 Objekt ScreenDetails 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