DocumentPictureInPicture: requestWindow() Methode

Limited availability

This feature is not Baseline because it does not work in some of the most widely-used browsers.

Experimentell: Dies ist eine experimentelle Technologie
Überprüfen Sie die Browser-Kompatibilitätstabelle sorgfältig, bevor Sie diese produktiv verwenden.

Sicherer Kontext: Diese Funktion ist nur in sicheren Kontexten (HTTPS) in einigen oder allen unterstützenden Browsern verfügbar.

Die requestWindow() Methode der DocumentPictureInPicture Schnittstelle ö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 im Picture-in-Picture-Fenster darstellt.

Die requestWindow() Methode erfordert transiente Aktivierung, d.h. sie muss als Reaktion auf eine Benutzeraktion wie einen Mausklick oder Tastendruck aufgerufen werden.

Syntax

js
requestWindow()
requestWindow(options)

Parameter

options Optional

Ein Optionsobjekt, das die folgenden Eigenschaften enthält:

disallowReturnToOpener Optional

Ein Boolean-Wert. Wenn auf true gesetzt, gibt diese Option dem Browser einen Hinweis, dass er keine Benutzeroberflächensteuerung anzeigen soll, die es dem Benutzer ermöglicht, zum ursprünglichen Tab zurückzukehren und das Picture-in-Picture-Fenster zu schließen. Standardmäßig false.

Zum Beispiel ist in Chromes Implementierung dieser Funktion die bereitgestellte Benutzeroberflächensteuerung ein "Zurück zum Tab"-Button in der oberen Leiste des Picture-in-Picture-Fensters:

Browserfenster, das einen eingebetteten Videoplayer und mehrere Steuerungstasten enthält, mit einem "Zurück zum Tab"-Button in der oberen Leiste, hervorgehoben mit einem roten Kasten

height Optional

Eine nicht negative Zahl, die die Höhe für den Viewport des Picture-in-Picture-Fensters in Pixeln darstellt. Standardwert ist 0.

preferInitialWindowPlacement Optional

Ein Boolean-Wert, der standardmäßig auf false gesetzt ist. Wenn auf true gesetzt, bewirkt dies, dass das Picture-in-Picture-Fenster immer wieder an der Stelle und Größe erscheint, an der es ursprünglich geöffnet wurde, wenn es geschlossen und dann erneut geöffnet wird. Wenn preferInitialWindowPlacement hingegen false ist, werden die Größe und Position des Picture-in-Picture-Fensters beim Schließen und Wiederöffnen gespeichert - es wird zum Beispiel an der vom Benutzer festgelegten vorherigen Position und Größe geöffnet.

width Optional

Eine nicht negative Zahl, die die Breite für den Viewport des Picture-in-Picture-Fensters in Pixeln darstellt. Standardwert ist 0.

Hinweis: Wenn height oder width angegeben wird, muss auch das andere angegeben werden, andernfalls wird ein Fehler ausgelöst. Wenn beide Werte nicht angegeben sind, auf 0 gesetzt oder zu groß eingestellt sind, wird der Browser die Werte entsprechend einschränken oder ignorieren, um ein vernünftiges Benutzererlebnis zu bieten. Die eingeschränkte Größe variiert je nach Implementierung, Anzeigegröße und anderen Faktoren.

Rückgabewert

Ein Promise, das mit einem Window-Objekt erfüllt wird, das den Browsing-Kontext im Picture-in-Picture-Fenster darstellt.

Ausnahmen

NotSupportedError DOMException

Wird ausgelöst, wenn die API ausdrücklich deaktiviert wurde (z.B. über Browsereinstellungen).

NotAllowedError DOMException

Wird ausgelöst, wenn:

RangeError DOMException

Wird ausgelöst, wenn nur einer von height und width festgelegt ist oder wenn height und width mit negativen Werten festgelegt sind.

Beispiele

js
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

Specification
Document Picture-in-Picture
# dom-documentpictureinpicture-requestwindow

Browser-Kompatibilität

BCD tables only load in the browser

Siehe auch