Picture-in-Picture API

Konzepte und Verwendung

Oft ist es hilfreich, ein Video in einem separaten Fenster außerhalb Ihrer Website abzuspielen. So können Sie es weiter ansehen und gleichzeitig zugehörige Inhalte der Anwendung im Blick behalten oder sogar eine andere Website aufrufen. Dazu könnten Sie einfach ein reguläres neues Browserfenster öffnen. Das hat jedoch zwei wesentliche Nachteile:

1. Sie müssen die gemeinsame Nutzung von Zustandsinformationen zwischen den beiden Fenstern selbst handhaben.
2. Das zusätzliche Anwendungsfenster 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 Arbeit, die nötig ist, um ein einzelnes <video>-Element in einem separaten, immer im Vordergrund befindlichen Fenster anzuzeigen.

Steuerelemente hinzufügen

Wenn über die Media Session API Media-Action-Handler eingerichtet wurden, fügt der Browser der Picture-in-Picture-Ansicht 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, Stil oder Layout von Inhalten automatisch angepasst werden, wenn ein Video zwischen dem Picture-in-Picture-Modus und der herkömmlichen Darstellung wechselt.

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 sich das schwebende Videofenster ein- und ausschalten lässt.

Instanzmethoden der Schnittstelle HTMLVideoElement

HTMLVideoElement.requestPictureInPicture()

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

Instanzmethoden der Schnittstelle Document

Document.exitPictureInPicture()

Fordert den User Agent auf, das Element im Picture-in-Picture-Modus an seinen ursprünglichen Platz zurückzubringen.

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 Schnittstelle HTMLVideoElement

HTMLVideoElement.disablePictureInPicture

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

Instanzeigenschaften der Schnittstelle Document

Document.pictureInPictureEnabled

Die Eigenschaft pictureInPictureEnabled gibt an, ob der Picture-in-Picture-Modus aktiviert werden kann. Ihr Wert ist false, wenn der Modus aus irgendeinem Grund nicht verfügbar ist – beispielsweise weil die Funktion "picture-in-picture" untersagt wurde oder der Picture-in-Picture-Modus nicht unterstützt wird.

Instanzeigenschaften der Schnittstellen Document oder ShadowRoot

Document.pictureInPictureElement / ShadowRoot.pictureInPictureElement

Die Eigenschaft pictureInPictureElement gibt an, welches Element derzeit im schwebenden Fenster angezeigt wird (beziehungsweise im Shadow DOM). Ist ihr 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 ihnen lässt sich erkennen, 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 seine Größe ändert.

Sicherheitsaspekte

Die Verfügbarkeit des Picture-in-Picture-Modus kann über die Permissions Policy gesteuert werden. Die Funktion für den Picture-in-Picture-Modus wird durch die Zeichenfolge "picture-in-picture" identifiziert. Der Standardwert ihrer Zulassungsliste ist *. Das bedeutet, dass der Picture-in-Picture-Modus in Dokumentkontexten der obersten Ebene sowie in eingebetteten Browsing-Kontexten zulässig ist, die vom selben Origin wie das oberste Dokument geladen wurden.

Beispiele

Picture-in-Picture-Modus ein- und ausschalten

In diesem Beispiel gibt es ein <video>-Element auf einer Webseite, ein <button>-Element zum Ein- und Ausschalten des Picture-in-Picture-Modus und ein Element zur Protokollierung der für das Beispiel relevanten Informationen. 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;
}

Zuerst 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 die von uns definierte Funktion togglePictureInPicture() auf. In togglePictureInPicture() prüft eine if-Anweisung den Wert des Attributs pictureInPictureElement von document.

• Ist der Wert null, wird kein Video in einem schwebenden Fenster angezeigt. Wir können daher 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. Dann können wir document.exitPictureInPicture() aufrufen, um das Video an seinen ursprünglichen Platz 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;
}

Durch Klicken auf die Schaltfläche „Toggle PiP“ können Nutzer 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