Picture-in-Picture API

PictureInPictureWindow

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

PictureInPictureEvent

Repräsentiert Ereignisse im Zusammenhang mit Picture-in-Picture, einschließlich enterpictureinpicture, leavepictureinpicture und resize.

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

HTMLVideoElement.requestPictureInPicture()

Fordert den User-Agent auf, das Video in den Picture-in-Picture-Modus zu versetzen.

Document.exitPictureInPicture()

Fordert den User-Agent auf, das Element im Picture-in-Picture-Modus zurück in seinen ursprünglichen Bereich zu versetzen.

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

HTMLVideoElement.disablePictureInPicture

Die disablePictureInPicture-Eigenschaft gibt dem User-Agent einen Hinweis darauf, dass dem Nutzer das Picture-in-Picture nicht vorgeschlagen oder automatisch angefordert werden soll.

Document.pictureInPictureEnabled

Die pictureInPictureEnabled-Eigenschaft sagt Ihnen, ob es möglich ist, den Bild-im-Bild-Modus zu aktivieren. Dies ist false, wenn der Bild-im-Bild-Modus aus irgendeinem Grund nicht verfügbar ist (z.B., das "picture-in-picture"-Feature wurde verboten oder der Bild-im-Bild-Modus wird nicht unterstützt).

Document.pictureInPictureElement / ShadowRoot.pictureInPictureElement

Die pictureInPictureElement-Eigenschaft sagt Ihnen, welches Element momentan im schwebenden Fenster (oder im Shadow-DOM) angezeigt wird. Wenn dies null ist, hat das Dokument (oder das Shadow-DOM) keinen Knoten, der derzeit im Picture-in-Picture-Modus ist.

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

enterpictureinpicture

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

leavepictureinpicture

Wird an ein HTMLVideoElement gesendet, wenn es den Bild-im-Bild-Modus verlässt.

resize

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

Wenn Medienaktionshandler über die Media Session API gesetzt wurden, dann werden geeignete Steuerungen für diese Aktionen vom Browser zur Bild-im-Bild-Überlagerung hinzugefügt. Zum Beispiel, wenn eine "nexttrack"-Aktion gesetzt wurde, könnte ein Überspringen-Button im Bild-im-Bild-Modus angezeigt werden. Es gibt keine Unterstützung für das Hinzufügen von benutzerdefinierten HTML-Buttons oder -Steuerungen.

Die :picture-in-picture CSS Pseudoklasse stimmt mit dem Videoelement überein, das sich momentan im Bild-im-Bild-Modus befindet, und ermöglicht es Ihnen, Ihre Stylesheets so zu konfigurieren, dass die Größe, der Stil oder das Layout von Inhalten automatisch angepasst wird, wenn ein Video zwischen Bild-im-Bild- und traditionellem Präsentationsmodus wechselt.

Die Verfügbarkeit des Bild-im-Bild-Modus kann mit den Permissions-Policy gesteuert werden. Die Bild-im-Bild-Modus-Funktion wird durch den String "picture-in-picture" identifiziert, mit einem Standard-Zulassungslistenwert von *, was bedeutet, dass der Bild-im-Bild-Modus in obersten Dokumentkontexten sowie in eingebetteten Browserkontexten, die aus demselben Ursprung wie das oberste Dokument geladen wurden, erlaubt ist.

In diesem Beispiel wird ein Video auf einer Webseite präsentiert. Durch Klicken auf den Button unten kann der Nutzer das schwebende Videofenster umschalten.

Dieser Code wird von einem Klick-Handler aufgerufen, wenn der Nutzer auf die Schaltfläche "Bild-im-Bild umschalten" klickt:

function togglePictureInPicture() {
  if (document.pictureInPictureElement) {
    document.exitPictureInPicture();
  } else if (document.pictureInPictureEnabled) {
    video.requestPictureInPicture();
  }
}

Dieser Block beginnt damit, den Wert der pictureInPictureElement-Eigenschaft des document anzusehen.

Wenn der Wert nicht null ist, ist es das Element, das momentan im Bild-im-Bild-Modus ist, das sich in einem schwebenden Fenster befindet. Wir rufen document.exitPictureInPicture() auf, um das Video zurück in seine ursprüngliche Box zu bringen.

Wenn der Wert null ist, befindet sich kein Video im schwebenden Fenster. So können wir ein Video anfordern, um in den Bild-im-Bild-Modus zu wechseln. Wir tun dies, indem wir HTMLVideoElement.requestPictureInPicture() auf dem <video>-Element aufrufen.

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