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
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 dasallowfullscreen
-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:
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>
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.
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:
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① |