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 vor der Verwendung auf produktiven Webseiten.

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-Browsingkontext. Sie gibt ein Promise zurück, das mit einer Window-Instanz erfüllt wird, die den Browsingkontext innerhalb des Picture-in-Picture-Fensters darstellt.

Die requestWindow()-Methode erfordert eine transiente Aktivierung, d.h. sie muss als Reaktion auf eine Benutzeraktion wie einen Mausklick oder das Drücken eines Knopfes aufgerufen werden.

Syntax

requestWindow()
requestWindow(options)

Parameter

options Optional

Ein Optionsobjekt, das die folgenden Eigenschaften enthält:

disallowReturnToOpener Optional

Ein boolescher Wert. Wenn auf true gesetzt, wird dem Browser angedeutet, dass keine Benutzeroberflächensteuerung angezeigt werden 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 der Chrome-Implementierung dieser Funktion die bereitgestellte Benutzeroberflächensteuerung ein "zurück zum Tab"-Button in der oberen Leiste des Picture-in-Picture-Fensters:

height Optional

Eine nicht-negative Zahl, die die Höhe des Viewports des Picture-in-Picture-Fensters in Pixeln angibt. Standardmäßig 0.

preferInitialWindowPlacement Optional

Ein boolescher Wert, der standardmäßig false ist. Wenn auf true gesetzt, wird das Picture-in-Picture-Fenster immer an der Position und Größe angezeigt, an der es ursprünglich geöffnet wurde, wenn es geschlossen und dann wieder geöffnet wird. Im Gegensatz dazu, wenn preferInitialWindowPlacement false ist, werden die Größe und Position des Picture-in-Picture-Fensters beim Schließen und erneuten Öffnen beibehalten — es wird an seiner vorherigen Position und Größe wieder geöffnet, beispielsweise wie vom Benutzer festgelegt.

width Optional

Eine nicht-negative Zahl, die die Breite des Viewports des Picture-in-Picture-Fensters in Pixeln angibt. Standardmäßig 0.

Hinweis: Wenn height oder width angegeben sind, müssen beide angegeben sein, ansonsten wird ein Fehler geworfen. Wenn beide Werte nicht angegeben, als 0 angegeben oder zu groß gesetzt sind, wird der Browser die Werte je nach Bedarf anpassen oder ignorieren, um ein vernünftiges Benutzererlebnis 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 Browsingkontext innerhalb des Picture-in-Picture-Fensters darstellt.

Ausnahmen

NotSupportedError DOMException

Wird geworfen, wenn die API explizit deaktiviert wurde (zum Beispiel über Browsereinstellungen).

NotAllowedError DOMException

Wird geworfen, wenn:

requestWindow() nicht von einem Top-Level-window-Objekt aufgerufen wird.
requestWindow() vom window-Objekt des Picture-in-Picture-Fensters aufgerufen wird (d.h. DocumentPictureInPicture.window).
requestWindow() ohne transiente Aktivierung aufgerufen wird.

RangeError DOMException

Wird geworfen, wenn nur einer von height und width gesetzt ist oder wenn height und width mit 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

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