DocumentPictureInPicture: Methode requestWindow()
Eingeschränkt verfügbar
Diese Funktion ist nicht Baseline, da sie in einigen der am weitesten verbreiteten Browser nicht funktioniert.
Want more browser support for this feature? Tell us why.
Sicherer Kontext: Diese Funktion ist nur in sicheren Kontexten (HTTPS) in einigen oder allen unterstützenden Browsern verfügbar.
Die Methode requestWindow() der Schnittstelle DocumentPictureInPicture ö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 repräsentiert.
Die Methode requestWindow() erfordert eine transiente Aktivierung. Sie muss also als Reaktion auf eine Benutzeraktion wie einen Mausklick oder einen Tastendruck aufgerufen werden.
Syntax
requestWindow()
requestWindow(options)
Parameter
optionsOptional-
Ein Optionsobjekt mit den folgenden Eigenschaften:
disallowReturnToOpenerOptional-
Ein boolescher Wert. Wenn er auf
truegesetzt ist, signalisiert diese Option dem Browser, dass er kein Bedienelement anzeigen sollte, mit dem Benutzer zum ursprünglichen Tab zurückkehren und das Picture-in-Picture-Fenster schließen können. Der Standardwert istfalse.In der Chrome-Implementierung dieser Funktion ist das entsprechende Bedienelement beispielsweise eine Schaltfläche „Zurück zum Tab“ 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. Der Standardwert ist
0. preferInitialWindowPlacementOptional-
Ein boolescher Wert mit dem Standardwert
false. Wenn er auftruegesetzt ist, erscheint das Picture-in-Picture-Fenster nach dem Schließen und erneuten Öffnen immer wieder an seiner ursprünglichen Position und in seiner ursprünglichen Größe. IstpreferInitialWindowPlacementdagegenfalse, werden Größe und Position des Picture-in-Picture-Fensters beim Schließen gespeichert. Beim erneuten Öffnen erscheint es dann beispielsweise an der zuvor vom Benutzer festgelegten Position und in der zuvor festgelegten Größe. widthOptional-
Eine nicht negative Zahl, die die Breite des Viewports des Picture-in-Picture-Fensters in Pixeln angibt. Der Standardwert ist
0.
Hinweis:
Wenn height oder width angegeben wird, muss auch der jeweils andere Wert angegeben werden. Andernfalls wird ein Fehler ausgelöst. Wenn beide Werte nicht angegeben werden, beide 0 sind oder zu groß gewählt werden, begrenzt oder ignoriert der Browser die Werte nach Bedarf, um eine angemessene Benutzererfahrung zu gewährleisten. Die resultierende Größe hängt unter anderem von der Implementierung und der Bildschirmgröße ab.
Rückgabewert
Ein Promise, das mit einer Window-Objektinstanz erfüllt wird, die den Browsing-Kontext innerhalb des Picture-in-Picture-Fensters repräsentiert.
Ausnahmen
NotSupportedErrorDOMException-
Wird ausgelöst, wenn die API ausdrücklich deaktiviert wurde (beispielsweise über die Browsereinstellungen).
NotAllowedErrorDOMException-
Wird ausgelöst, wenn:
requestWindow()nicht von einemwindow-Objekt der obersten Ebene aus aufgerufen wird.requestWindow()vomwindow-Objekt des Picture-in-Picture-Fensters aus aufgerufen wird (d.h.DocumentPictureInPicture.window).requestWindow()ohne transiente Aktivierung aufgerufen wird.
RangeError-
Wird ausgelöst, wenn nur einer der Werte
heightundwidthfestgelegt ist oder wennheightundwidthauf negative Werte gesetzt werden.
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 |