Picture-in-Picture API

Die Picture-in-Picture API erlaubt es Websites, ein schwebendes, immer im Vordergrund stehendes Videofenster zu erstellen. Dadurch können Nutzer Medien weiterhin konsumieren, während sie mit anderen Websites oder Anwendungen auf ihrem Gerät interagieren.

Schnittstellen

PictureInPictureWindow

Repräsentiert das schwebende Videofenster; enthält die Eigenschaften width und height sowie eine onresize-Ereignishandler-Eigenschaft.

PictureInPictureEvent

Repräsentiert ereignisbezogene Ereignisse für Picture-in-Picture, einschließlich enterpictureinpicture, leavepictureinpicture und resize.

Methodeninstanzen

Die Picture-in-Picture API fügt den Schnittstellen HTMLVideoElement und Document Methoden hinzu, um das schwebende Videofenster ein- oder auszuschalten.

Methodeninstanzen auf der HTMLVideoElement-Schnittstelle

HTMLVideoElement.requestPictureInPicture()

Fordert den Nutzeragenten auf, das Video in den Picture-in-Picture-Modus zu versetzen

Methodeninstanzen auf der Document-Schnittstelle

Document.exitPictureInPicture()

Fordert den Nutzeragenten auf, das Element im Picture-in-Picture-Modus zurück in seinen ursprünglichen Rahmen zu bringen.

Instanzeigenschaften

Die Picture-in-Picture API erweitert die Schnittstellen HTMLVideoElement, Document, und ShadowRoot mit Eigenschaften, die verwendet werden können, um zu bestimmen, ob der schwebende Videofenstermodus unterstützt und verfügbar ist, ob der Picture-in-Picture-Modus derzeit aktiv ist, und welches Video schwebt.

Instanzeigenschaften auf der HTMLVideoElement-Schnittstelle

HTMLVideoElement.disablePictureInPicture

Die Eigenschaft disablePictureInPicture gibt einen Hinweis an den Nutzeragenten, die Picture-in-Picture-Funktion den Nutzern nicht vorzuschlagen oder sie automatisch anzufordern.

Instanzeigenschaften auf der Document-Schnittstelle

Document.pictureInPictureEnabled

Die Eigenschaft pictureInPictureEnabled gibt an, ob es möglich ist, den Picture-in-Picture-Modus zu aktivieren. Dies ist false, wenn der Picture-in-Picture-Modus aus irgendeinem Grund nicht verfügbar ist (z.B. wurde die Funktion "picture-in-picture" nicht erlaubt, oder der Picture-in-Picture-Modus wird nicht unterstützt).

Instanzeigenschaften auf den Document- oder ShadowRoot-Schnittstellen

Document.pictureInPictureElement / ShadowRoot.pictureInPictureElement

Die Eigenschaft pictureInPictureElement teilt Ihnen mit, welches Element derzeit im schwebenden Fenster (oder im Shadow DOM) angezeigt wird. Wenn dieser Wert null ist, hat das Dokument (oder das Shadow DOM) derzeit keinen Knoten im Picture-in-Picture-Modus.

Ereignisse

Die Picture-in-Picture API definiert drei Ereignisse, die verwendet werden können, um zu erkennen, wann der Picture-in-Picture-Modus ein- oder ausgeschaltet wird und wann das schwebende Videofenster seine Größe ändert.

enterpictureinpicture

Wird an ein HTMLVideoElement gesendet, wenn es in den Picture-in-Picture-Modus wechselt.

leavepictureinpicture

Wird an ein HTMLVideoElement gesendet, wenn es den Picture-in-Picture-Modus verlässt.

resize

Wird an ein PictureInPictureWindow gesendet, wenn es seine Größe ändert.

Hinzufügen von Steuerungen

Wenn Medienaktionshandler über die Media Session API eingerichtet wurden, dann werden die entsprechenden Steuerungen für diese Aktionen vom Browser in die Picture-in-Picture-Überlagerung hinzugefügt. Wenn beispielsweise eine "nexttrack"-Aktion gesetzt wurde, könnte eine Überspringen-Taste in der Picture-in-Picture-Ansicht angezeigt werden. Es gibt keine Unterstützung für das Hinzufügen benutzerdefinierter HTML-Schaltflächen oder -Steuerungen.

Steuerung des Stylings

Die :picture-in-picture CSS Pseudoklasse stimmt mit dem derzeit im Picture-in-Picture-Modus befindlichen Videoelement überein, wodurch Sie Ihre Stylesheets so konfigurieren können, dass Größe, Stil oder Layout des Inhalts automatisch angepasst werden, wenn ein Video zwischen Picture-in-Picture und herkömmlichen Präsentationsmodi wechselt.

Steuerung des Zugriffs

Die Verfügbarkeit des Picture-in-Picture-Modus kann mit der Permissions Policy gesteuert werden. Die Picture-in-Picture-Modus-Funktion wird durch den String "picture-in-picture" identifiziert, mit einem Standardwert der Erlaubtenliste von *, was bedeutet, dass der Picture-in-Picture-Modus in obersten Dokumentkontexten sowie in eingebetteten Browsing-Kontexten, die von derselben Quelle wie das oberste Dokument geladen werden, erlaubt ist.

Beispiele

Umschalten des Picture-in-Picture-Modus

In diesem Beispiel haben wir ein <video>-Element auf einer Webseite, ein <button>, um Picture-in-Picture umzuschalten, und ein Element, um Informationen zu protokollieren, die für das Beispiel relevant sind. Das <button>-Element ist initial deaktiviert, bis wir die Unterstützung des Browsers festgestellt haben.

<video
 src="/shared-assets/videos/friday.mp4"
 id="video"
 muted
 controls
 loop
 width="300"></video>
<button id="pip-button" disabled>Toggle PiP</button>
<pre id="log"></pre>

body {
 font:
 14px "Open Sans",
 sans-serif;
 padding: 0.5em;
}
button {
 display: block;
 margin-block: 1rem;
}

Zuerst überprüfen wir, ob der Browser PiP mit document.pictureInPictureEnabled unterstützt, und wenn es nicht unterstützt wird, protokollieren wir diese Information im <pre>-Element. Wenn es im Browser verfügbar ist, können wir das Umschalten zum Ein- und Austreten des PiP aktivieren.

Für die Steuerungen ruft ein Ereignislistener auf dem <button>-Element eine von uns definierte togglePictureInPicture()-Funktion auf. In togglePictureInPicture() überprüft eine if-Anweisung den Wert des Attributs pictureInPictureElement des document.

• Wenn der Wert null ist, befindet sich kein Video in einem schwebenden Fenster, daher können wir das Video anfordern, um in den Picture-in-Picture-Modus zu wechseln. Wir tun dies, indem wir HTMLVideoElement.requestPictureInPicture() auf dem <video>-Element aufrufen.
• Wenn der Wert nicht null ist, befindet sich derzeit ein Element im Picture-in-Picture-Modus. Dann können wir document.exitPictureInPicture() aufrufen, um das Video zurück in seinen ursprünglichen Kasten zu holen und den Picture-in-Picture-Modus zu verlassen.

const video = document.getElementById("video");
const pipButton = document.getElementById("pip-button");
const log = document.getElementById("log");
if (document.pictureInPictureEnabled) {
 pipButton.removeAttribute("disabled");
} else {
 log.innerText = "PiP not supported. Check browser compatibility for details.";
}
function togglePictureInPicture() {
 if (document.pictureInPictureElement) {
 document.exitPictureInPicture();
 } else {
 video.requestPictureInPicture();
 }
}
pipButton.addEventListener("click", togglePictureInPicture);

:picture-in-picture {
 outline: 5px dashed green;
}

Durch Klicken auf die "Toggle PiP"-Schaltfläche kann der Nutzer zwischen der Wiedergabe des Videos auf der Seite und in einem schwebenden Fenster umschalten:

Spezifikationen

Browser-Kompatibilität

Siehe auch

• HTMLVideoElement.requestPictureInPicture()
• HTMLVideoElement.disablePictureInPicture
• Document.pictureInPictureEnabled
• Document.exitPictureInPicture()
• Document.pictureInPictureElement
• :picture-in-picture
• Die Document Picture-in-Picture API