Picture-in-Picture API

Konzepte und Verwendung

Es ist oft hilfreich, ein Video in einem separaten Fenster zur restlichen Website abzuspielen, um weiterhin schauen zu können, während verbundene App-Inhalte angezeigt werden oder sogar um eine andere Website zu betrachten. Dies könnte man erreichen, indem man einfach ein reguläres neues Browserfenster öffnet, aber das hat zwei wesentliche Probleme:

1. Sie müssen die gemeinsame Nutzung von Statusinformationen zwischen den beiden Fenstern handhaben.
2. Das zusätzliche App-Fenster bleibt nicht immer im Vordergrund und kann daher von anderen Fenstern verdeckt werden.

Die Picture-in-Picture-API für <video> löst diese Probleme, indem sie den Großteil der Komplexität verwaltet, ein einzelnes <video>-Element in ein separates, immer im Vordergrund befindliches Fenster zu platzieren.

Hinzufügen von Steuerelementen

Wenn Media-Session-Aktions-Handler über die Media Session API festgelegt wurden, werden passende Steuerelemente für diese Aktionen vom Browser dem Bild-in-Bild-Overlay hinzugefügt. Zum Beispiel, wenn eine "nexttrack"-Aktion festgelegt wurde, könnte ein Überspringen-Button in der Bild-in-Bild-Ansicht angezeigt werden. Es gibt keine Unterstützung für das Hinzufügen von benutzerdefinierten HTML-Buttons oder -Steuerelementen.

Steuerung des Stylings

Die :picture-in-picture CSS Pseudoklasse wählt das Videoelement aus, das sich derzeit im Bild-in-Bild-Modus befindet, und ermöglicht Ihnen, Ihre Stylesheets so zu konfigurieren, dass Größe, Stil oder Layout des Inhalts automatisch angepasst werden, wenn ein Video zwischen Bild-in-Bild- und traditioneller Präsentationsweise wechselt.

Sicherheitserwägungen

Die Verfügbarkeit des Bild-in-Bild-Modus kann über die Permissions Policy kontrolliert werden. Die Funktion des Bild-in-Bild-Modus wird durch den String "picture-in-picture" identifiziert, mit einem Standard-Whitelist-Wert von *, was bedeutet, dass der Bild-in-Bild-Modus in Dokumentkontexten auf oberster Ebene sowie in eingebetteten Browserkontexten, die aus derselben Herkunft wie das oberste Dokument geladen wurden, erlaubt ist.

Schnittstellen

PictureInPictureWindow

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

PictureInPictureEvent

Stellt Ereignisse im Zusammenhang mit Bild-in-Bild dar, einschließlich enterpictureinpicture, leavepictureinpicture und resize.

Instanzmethoden

Die Picture-in-Picture-API fügt den Schnittstellen HTMLVideoElement und Document Methoden hinzu, um das schwebende Videofenster umschalten zu können.

Instanzmethoden in der HTMLVideoElement-Schnittstelle

HTMLVideoElement.requestPictureInPicture()

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

Instanzmethoden in der Document-Schnittstelle

Document.exitPictureInPicture()

Fordert den Benutzeragenten auf, das Element, das sich im Bild-in-Bild-Modus befindet, zurück in seine ursprüngliche Box zu versetzen.

Instanzeigenschaften

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

Instanzeigenschaften in der HTMLVideoElement-Schnittstelle

HTMLVideoElement.disablePictureInPicture

Die Eigenschaft disablePictureInPicture gibt einen Hinweis an den Benutzeragenten, den Bild-in-Bild-Modus den Benutzern nicht vorzuschlagen oder ihn automatisch anzufordern.

Instanzeigenschaften in der Document-Schnittstelle

Document.pictureInPictureEnabled

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

Instanzeigenschaften in den Document oder ShadowRoot-Schnittstellen

Document.pictureInPictureElement / ShadowRoot.pictureInPictureElement

Die Eigenschaft pictureInPictureElement informiert Sie darüber, welches Element derzeit im schwebenden Fenster (oder im Shadow DOM) angezeigt wird. Wenn dies null ist, hat das Dokument (oder das Shadow DOM) derzeit kein Knoten im Bild-in-Bild-Modus.

Ereignisse

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

enterpictureinpicture

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

leavepictureinpicture

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

resize

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

Beispiele

Umschalten des Bild-in-Bild-Modus

In diesem Beispiel haben wir ein <video>-Element in einer Webseite, ein <button> zum Umschalten des Bild-in-Bild-Modus und ein Element, um relevante Informationen für das Beispiel zu protokollieren. Das <button>-Element ist anfänglich disabled, bis wir die Browserunterstützung 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 prüfen wir, ob der Browser PiP mit document.pictureInPictureEnabled unterstützt, und wenn es nicht unterstützt wird, protokollieren wir diese Information in das <pre>-Element. Wenn es im Browser verfügbar ist, können wir das Umschalten aktivieren, um in den und aus dem PiP zu wechseln.

Für die Steuerung ruft ein Ereignislistener am <button>-Element eine togglePictureInPicture()-Funktion auf, die wir definiert haben. In togglePictureInPicture() überprüft eine if-Anweisung den Wert des Attributes pictureInPictureElement des document.

• Wenn der Wert null ist, befindet sich kein Video in einem schwebenden Fenster, sodass wir das Video anfordern können, in den Bild-in-Bild-Modus zu wechseln. Dies tun wir, indem wir HTMLVideoElement.requestPictureInPicture() am <video>-Element aufrufen.
• Wenn der Wert nicht null ist, befindet sich derzeit ein Element im Bild-in-Bild-Modus. Wir können dann document.exitPictureInPicture() aufrufen, um das Video zurück in seine ursprüngliche Box zu bringen und den Bild-in-Bild-Modus zu beenden.

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;
}

Das Klicken auf die "Toggle PiP"-Schaltfläche ermöglicht es dem Benutzer, zwischen dem Abspielen des Videos auf der Seite und in einem schwebenden Fenster umzuschalten:

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