Picture-in-Picture API

Konzepte und Verwendung

Oft ist es hilfreich, ein Video in einem separaten Fenster vom Rest Ihrer Website abzuspielen. So können Sie es weiter ansehen und gleichzeitig zugehörige App-Inhalte im Blick behalten oder sogar eine andere Website betrachten. Sie könnten dafür einfach ein gewöhnliches neues Browserfenster öffnen. Das hat jedoch zwei wesentliche Nachteile:

1. Sie müssen den Austausch von Zustandsinformationen 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 und übernimmt den Großteil der Komplexität, die damit verbunden ist, ein einzelnes <video>-Element in einem separaten, immer im Vordergrund bleibenden Fenster anzuzeigen.

Steuerelemente hinzufügen

Wenn über die Media Session API Media-Action-Handler eingerichtet wurden, fügt der Browser dem Picture-in-Picture-Fenster passende Steuerelemente für diese Aktionen hinzu. Wenn beispielsweise eine "nexttrack"-Aktion eingerichtet wurde, kann in der Picture-in-Picture-Ansicht eine Schaltfläche zum Überspringen angezeigt werden. Das Hinzufügen eigener HTML-Schaltflächen oder -Steuerelemente wird nicht unterstützt.

Darstellung steuern

Die CSS-Pseudoklasse :picture-in-picture trifft auf das Videoelement zu, das sich gerade im Picture-in-Picture-Modus befindet. Damit können Sie Ihre Stylesheets so konfigurieren, dass Größe, Darstellung oder Layout von Inhalten automatisch angepasst werden, wenn ein Video zwischen dem Picture-in-Picture-Modus und der herkömmlichen Darstellung wechselt.

Sicherheitsaspekte

Die Verfügbarkeit des Picture-in-Picture-Modus lässt sich über die Permissions Policy steuern. Die Picture-in-Picture-Funktion wird durch die Zeichenfolge "picture-in-picture" identifiziert. Der Standardwert ihrer Allowlist ist *. Das bedeutet, dass der Picture-in-Picture-Modus sowohl in Dokumentkontexten der obersten Ebene als auch in verschachtelten Browsing-Kontexten zulässig ist, die vom selben Ursprung wie das oberste Dokument geladen wurden.

Schnittstellen

PictureInPictureWindow

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

PictureInPictureEvent

Repräsentiert Picture-in-Picture-bezogene Ereignisse, darunter enterpictureinpicture, leavepictureinpicture und resize.

Instanzmethoden

Die Picture-in-Picture API ergänzt die Schnittstellen HTMLVideoElement und Document um Methoden, mit denen das schwebende Videofenster ein- und ausgeschaltet werden kann.

Instanzmethoden der HTMLVideoElement-Schnittstelle

HTMLVideoElement.requestPictureInPicture()

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

Instanzmethoden der Document-Schnittstelle

Document.exitPictureInPicture()

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

Instanzeigenschaften

Die Picture-in-Picture API ergänzt die Schnittstellen HTMLVideoElement, Document und ShadowRoot um Eigenschaften. Mit ihnen lässt sich feststellen, ob der Modus für schwebende Videofenster unterstützt wird und verfügbar ist, ob der Picture-in-Picture-Modus derzeit aktiv ist und welches Video im schwebenden Fenster angezeigt wird.

Instanzeigenschaften der HTMLVideoElement-Schnittstelle

HTMLVideoElement.disablePictureInPicture

Die Eigenschaft disablePictureInPicture gibt dem User Agent einen Hinweis, Benutzern den Picture-in-Picture-Modus nicht vorzuschlagen und ihn nicht automatisch anzufordern.

Instanzeigenschaften der Document-Schnittstelle

Document.pictureInPictureEnabled

Die Eigenschaft pictureInPictureEnabled gibt an, ob der Picture-in-Picture-Modus aktiviert werden kann. Sie ist false, wenn der Picture-in-Picture-Modus aus irgendeinem Grund nicht verfügbar ist (z. B. weil die Funktion "picture-in-picture" nicht zugelassen wurde oder der Picture-in-Picture-Modus nicht unterstützt wird).

Instanzeigenschaften der Document- oder ShadowRoot-Schnittstelle

Document.pictureInPictureElement / ShadowRoot.pictureInPictureElement

Die Eigenschaft pictureInPictureElement gibt an, welches Element derzeit im schwebenden Fenster angezeigt wird (beziehungsweise im Shadow DOM). Ist der Wert null, befindet sich derzeit kein Knoten des Dokuments (beziehungsweise des Shadow DOM) im Picture-in-Picture-Modus.

Ereignisse

Die Picture-in-Picture API definiert drei Ereignisse, mit denen sich erkennen lässt, wann der Picture-in-Picture-Modus ein- oder ausgeschaltet und wann die Größe des schwebenden Videofensters geändert wird.

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 dessen Größe ändert.

Beispiele

Picture-in-Picture-Modus ein- und ausschalten

In diesem Beispiel gibt es auf einer Webseite ein <video>-Element, ein <button>-Element zum Ein- und Ausschalten von Picture-in-Picture sowie ein Element, in dem für das Beispiel relevante Informationen protokolliert werden. Das <button>-Element ist zunächst disabled, bis wir festgestellt haben, ob der Browser die Funktion unterstützt.

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

Zunächst prüfen wir mit document.pictureInPictureEnabled, ob der Browser PiP unterstützt. Falls nicht, protokollieren wir diese Information im <pre>-Element. Ist PiP im Browser verfügbar, können wir die Schaltfläche zum Ein- und Ausschalten aktivieren.

Für die Steuerung ruft ein Event-Listener am <button>-Element eine von uns definierte Funktion togglePictureInPicture() auf. In togglePictureInPicture() prüft eine if-Anweisung den Wert des Attributs pictureInPictureElement von document.

• Ist der Wert null, befindet sich kein Video in einem schwebenden Fenster. Wir können dann anfordern, das Video in den Picture-in-Picture-Modus zu versetzen. Dazu rufen wir HTMLVideoElement.requestPictureInPicture() für das <video>-Element auf.
• Ist der Wert nicht null, befindet sich derzeit ein Element im Picture-in-Picture-Modus. Wir können dann document.exitPictureInPicture() aufrufen, um das Video in seinen ursprünglichen Bereich zurückzubringen 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;
}

Mit einem Klick auf die Schaltfläche „Toggle PiP“ kann der Benutzer zwischen der Wiedergabe des Videos auf der Seite und in einem schwebenden Fenster wechseln:

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