DocumentPictureInPicture: requestWindow() Methode
Eingeschränkt verfügbar
Diese Funktion ist nicht Baseline, da sie in einigen der am weitesten verbreiteten Browser nicht funktioniert.
Sicherer Kontext: Diese Funktion ist nur in sicheren Kontexten (HTTPS) in einigen oder allen unterstützenden Browsern verfügbar.
Die requestWindow() Methode des
DocumentPictureInPicture Interfaces öffnet das Picture-in-Picture-Fenster für den aktuellen Haupt-Browsing-Kontext. Sie gibt ein Promise zurück, das mit einer Window Instanz erfüllt wird, die den Browsing-Kontext innerhalb des Picture-in-Picture-Fensters darstellt.
Die requestWindow() Methode erfordert transiente Aktivierung, d.h. sie muss als Reaktion auf eine Benutzeraktion wie einen Mausklick oder einen Tastendruck aufgerufen werden.
Syntax
requestWindow()
requestWindow(options)
Parameter
optionsOptional-
Ein Optionsobjekt, das die folgenden Eigenschaften enthält:
disallowReturnToOpenerOptional-
Ein boolescher Wert. Wenn auf
truegesetzt, weist diese Option den Browser an, kein UI-Steuerelement anzuzeigen, das dem Benutzer erlaubt, in den ursprünglichen Tab zurückzukehren und das Picture-in-Picture-Fenster zu schließen. Standardwert istfalse.Zum Beispiel ist in der Chrome-Implementierung dieser Funktion das bereitgestellte UI-Steuerelement eine "Zurück zum Tab"-Schaltfläche in der oberen Leiste des Picture-in-Picture-Fensters:
heightOptional-
Eine nicht-negative Zahl, die die Höhe des Viewports des Picture-in-Picture-Fensters in Pixeln angibt. Standardwert ist
0. preferInitialWindowPlacementOptional-
Ein boolescher Wert, der standardmäßig
falseist. Wenn auftruegesetzt, sorgt er dafür, dass das Picture-in-Picture-Fenster immer an der Position und Größe erscheint, an der es ursprünglich geöffnet wurde, wenn es geschlossen und dann wieder geöffnet wird. Im Gegensatz dazu wird, wennpreferInitialWindowPlacementfalseist, die Größe und Position des Picture-in-Picture-Fensters beim Schließen und Wiederöffnen gespeichert — es wird an seiner vorherigen Position und Größe wieder geöffnet, wie z.B. vom Benutzer eingestellt. widthOptional-
Eine nicht-negative Zahl, die die Breite des Viewports des Picture-in-Picture-Fensters in Pixeln angibt. Standardwert ist
0.
Hinweis:
Wenn eine von height oder width angegeben ist, muss die andere ebenfalls angegeben werden, ansonsten wird ein Fehler geworfen. Wenn beide Werte nicht angegeben, als 0 angegeben oder zu groß gesetzt werden, wird der Browser die Werte anpassen oder ignorieren, um eine angemessene Benutzererfahrung zu gewährleisten. Die angepasste Größe variiert je nach Implementierung, Displaygröße und anderen Faktoren.
Rückgabewert
Ein Promise, das mit einem Window Objekt erfüllt wird, das den Browsing-Kontext innerhalb des Picture-in-Picture-Fensters darstellt.
Ausnahmen
NotSupportedErrorDOMException-
Wird geworfen, wenn die API ausdrücklich deaktiviert wurde (zum Beispiel über die Browsereinstellungen).
NotAllowedErrorDOMException-
Wird geworfen, wenn:
requestWindow()nicht von einem top-levelwindowObjekt aus aufgerufen wird.requestWindow()aus demwindowObjekt des Picture-in-Picture-Fensters (d.h.DocumentPictureInPicture.window) aufgerufen wird.requestWindow()ohne transiente Aktivierung aufgerufen wird.
RangeErrorDOMException-
Wird geworfen, wenn nur eine von
heightundwidthgesetzt ist, oder wennheightundwidthmit negativen Werten gesetzt sind.
Beispiele
const videoPlayer = document.getElementById("player");
// …
// Open a Picture-in-Picture window with all options set
const pipWindow = await window.documentPictureInPicture.requestWindow({
width: videoPlayer.clientWidth,
height: videoPlayer.clientHeight,
disallowReturnToOpener: true,
preferInitialWindowPlacement: true,
});
// …
Spezifikationen
| Spezifikation |
|---|
| Document Picture-in-Picture Specification # dom-documentpictureinpicture-requestwindow |