Picture-in-Picture API

Limited availability

This feature is not Baseline because it does not work in some of the most widely-used browsers.

Die Picture-in-Picture API ermöglicht es Websites, ein schwebendes, immer im Vordergrund befindliches Videofenster zu erstellen. Dies erlaubt es Benutzern, Medien weiter zu konsumieren, während sie mit anderen Seiten oder Anwendungen auf ihrem Gerät interagieren.

Hinweis: Die Document Picture-in-Picture API erweitert die Picture-in-Picture API, um es zu ermöglichen, das immer im Vordergrund befindliche Fenster mit beliebigem HTML-Inhalt zu füllen, nicht nur mit einem Video.

Schnittstellen

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.

Instanzmethoden

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

Instanzmethoden auf der HTMLVideoElement-Schnittstelle

HTMLVideoElement.requestPictureInPicture(): Fordert den Benutzeragenten auf, das Video in den Picture-in-Picture-Modus zu versetzen.

Instanzmethoden auf der Document-Schnittstelle

Document.exitPictureInPicture(): Fordert den Benutzeragenten auf, das Element im Picture-in-Picture-Modus in seinen ursprünglichen Bereich zurückzuführen.

Instanzeigenschaften

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

Instanzeigenschaften auf der HTMLVideoElement-Schnittstelle

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

Instanzeigenschaften auf der Document-Schnittstelle

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

Instanzeigenschaften auf den Schnittstellen Document oder ShadowRoot

Document.pictureInPictureElement / ShadowRoot.pictureInPictureElement: Die Eigenschaft pictureInPictureElement gibt an, welches Element derzeit im schwebenden Fenster (oder im Shadow DOM) angezeigt wird. Wenn dies null ist, hat das Dokument (oder das Shadow DOM) derzeit keine Knoten im Picture-in-Picture-Modus.

Ereignisse

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

Hinzufügen von Steuerelementen

Wenn Medienaktionshandler über die Media Session API gesetzt wurden, dann werden geeignete Steuerelemente für diese Aktionen vom Browser zum Picture-in-Picture-Overlay hinzugefügt. Wenn zum Beispiel eine "nexttrack"-Aktion gesetzt wurde, könnte ein Skip-Button in der Picture-in-Picture-Ansicht angezeigt werden. Es gibt keine Unterstützung für das Hinzufügen benutzerdefinierter HTML-Buttons oder -Steuerelemente.

Steuerung des Stylings

Die :picture-in-picture CSS Pseudoklasse stimmt mit dem Videoelement überein, das sich aktuell im Picture-in-Picture-Modus befindet, und ermöglicht es Ihnen, Ihre Stylesheets so zu konfigurieren, dass die Größe, der Stil oder das Layout des Inhalts automatisch angepasst werden, wenn ein Video zwischen Picture-in-Picture und traditionellen Präsentationsmodi wechselt.

Steuerung des Zugriffs

Die Verfügbarkeit des Picture-in-Picture-Modus kann mithilfe der Permissions Policy gesteuert werden. Die Funktion des Picture-in-Picture-Modus wird durch den String "picture-in-picture" identifiziert, mit einem standardmäßigen Allowlist-Wert von *, was bedeutet, dass der Picture-in-Picture-Modus in obersten Dokumentkontexten sowie in verschachtelten Browsing-Kontexten erlaubt ist, die von der gleichen Herkunft wie das oberste Dokument geladen wurden.

Beispiele

Umschalten zwischen Picture-in-Picture-Modus

In diesem Beispiel haben wir ein <video>-Element in einer Webseite, ein <button>, um Picture-in-Picture umzuschalten, und ein Element, um Informationen zu protokollieren, die für das Beispiel relevant sind. Das <button>-Element ist anfänglich disabled, bis wir die Unterstützung des Browsers festgestellt haben.

html

<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 überprü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 den Toggle aktivieren, um PiP ein- und auszuschalten.

Für die Steuerelemente ruft ein Ereignis-Listener auf dem <button>-Element eine togglePictureInPicture()-Funktion auf, die wir definiert haben. In togglePictureInPicture() prüft eine if-Anweisung den Wert des pictureInPictureElement Attributs des document.

Wenn der Wert null ist, ist kein Video in einem schwebenden Fenster, sodass wir das Video bitten können, in den Picture-in-Picture-Modus zu wechseln. Dies tun wir, indem wir HTMLVideoElement.requestPictureInPicture() auf dem <video>-Element aufrufen.
Wenn der Wert nicht null ist, befindet sich ein Element derzeit im Picture-in-Picture-Modus. Wir können dann document.exitPictureInPicture() aufrufen, um das Video zurück in seinen ursprünglichen Bereich zu bringen 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);

css

:picture-in-picture {
  outline: 5px dashed green;
}

Das Klicken auf den "Toggle PiP"-Button ermöglicht es dem Benutzer, zwischen der Wiedergabe des Videos auf der Seite und in einem schwebenden Fenster zu wechseln:

Spezifikationen

Specification
Picture-in-Picture # interface-picture-in-picture-window

Browser-Kompatibilität

Siehe auch

Help improve MDN

Learn how to contribute Diese Seite wurde automatisch aus dem Englischen übersetzt.

Übersetzung auf GitHub anzeigen • Fehler mit dieser Übersetzung melden