Picture-in-Picture API

PictureInPictureWindow

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

PictureInPictureEvent

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

Die Picture-in-Picture-API fügt Methoden zu den Schnittstellen HTMLVideoElement und Document hinzu, um das Umschalten des schwebenden Videofensters zu ermöglichen.

HTMLVideoElement.requestPictureInPicture()

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

Document.exitPictureInPicture()

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

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

HTMLVideoElement.disablePictureInPicture

Die disablePictureInPicture-Eigenschaft gibt dem Benutzeragenten einen Hinweis, das Picture-in-Picture den Benutzern nicht vorzuschlagen oder es automatisch anzufordern.

Document.pictureInPictureEnabled

Die pictureInPictureEnabled-Eigenschaft teilt Ihnen mit, 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. wenn die "picture-in-picture"-Funktion nicht erlaubt wurde oder der Picture-in-Picture-Modus nicht unterstützt wird).

Document.pictureInPictureElement / ShadowRoot.pictureInPictureElement

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

Die Picture-in-Picture-API definiert drei Ereignisse, die verwendet werden können, um zu erkennen, wann der Picture-in-Picture-Modus umgeschaltet 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 sich seine Größe ändert.

Wenn Medienaktions-Handler über die Media Session API festgelegt wurden, werden die entsprechenden Steuerelemente für diese Aktionen vom Browser zur Picture-in-Picture-Überlagerung hinzugefügt. Wenn beispielsweise eine "nexttrack"-Aktion festgelegt wurde, könnte ein Überspringen-Knopf im Picture-in-Picture-Modus angezeigt werden. Es gibt keine Unterstützung für das Hinzufügen benutzerdefinierter HTML-Schaltflächen oder Steuerelemente.

Die :picture-in-picture CSS Pseudo-Klasse entspricht dem Video-Element, das sich derzeit im Picture-in-Picture-Modus befindet, sodass Sie Ihre Stylesheets so konfigurieren können, dass Größe, Stil oder Layout von Inhalten automatisch angepasst werden, wenn ein Video zwischen dem Picture-in-Picture- und dem traditionellen Präsentationsmodus wechselt.

Die Verfügbarkeit des Picture-in-Picture-Modus kann mithilfe der Permissions Policy gesteuert werden. Die Picture-in-Picture-Modus-Funktion wird durch den String "picture-in-picture" identifiziert, mit einem Standard-Erlaubnislistenwert von *, was bedeutet, dass der Picture-in-Picture-Modus in Top-Level-Dokument-Kontexten sowie in geschachtelten Browsing-Kontexten, die von demselben Ursprung wie das oberste Dokument geladen werden, erlaubt ist.

In diesem Beispiel wird ein Video auf einer Webseite präsentiert. Mit dem Klick auf die Schaltfläche unten kann der Benutzer das schwebende Videofenster umschalten.

Dieser Code wird von einem Klick-Handler aufgerufen, wenn der Benutzer auf die Schaltfläche "Toggle Picture-in-Picture" klickt:

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

Dieser Block beginnt damit, den Wert des Attributs pictureInPictureElement des document zu betrachten.

Wenn der Wert nicht null ist, ist es das Element, das sich derzeit im Picture-in-Picture-Modus befindet, also in einem schwebenden Fenster. Wir rufen document.exitPictureInPicture() auf, um das Video zurück in seinen ursprünglichen Bereich zu bringen.

Wenn der Wert null ist, befindet sich kein Video im schwebenden Fenster. Daher können wir ein Video anfordern, in den Picture-in-Picture-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