HTMLVideoElement: leavepictureinpicture — Ereignis · JavaScript-Referenz

Signatur

videoElement.addEventListener("leavepictureinpicture", handler)

Beschreibung

Das Ereignis leavepictureinpicture gehört zur Picture-in-Picture-API. Es wird an einem HTMLVideoElement ausgelöst, nachdem das schwebende Bild-in-Bild-Fenster geschlossen wurde und das Video wieder im normalen Seitenlayout angezeigt wird. Das Ereignis ist vom Typ PictureInPictureEvent, blubbert (bubbles: true) und ist nicht abbrechbar.

Es spielt keine Rolle, wie der Modus verlassen wurde: per document.exitPictureInPicture(), über die Schließen- bzw. „Zurück zum Tab“-Schaltfläche des PiP-Fensters, weil ein anderes Video in den PiP-Modus gewechselt ist, oder weil das Element aus dem DOM entfernt wurde. Deshalb ist dieses Ereignis der zuverlässige Ort, um die Oberfläche zurückzusetzen, statt das Promise von exitPictureInPicture() auszuwerten.

Typische Einsatzzwecke:

PiP-Schaltfläche wieder auf „Bild-in-Bild öffnen“ umstellen oder Platzhalter ausblenden.
Die Wiedergabe pausieren, wenn der Nutzer das PiP-Fenster schließt (Chrome pausiert beim Schließen je nach Aktion, „Zurück zum Tab“ setzt fort).
Resize-Listener am PictureInPictureWindow entfernen oder Analysedaten erfassen.

Registriert wird der Handler per addEventListener("leavepictureinpicture", …) oder über die Eigenschaft onleavepictureinpicture. Das Gegenstück ist enterpictureinpicture.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname `"leavepictureinpicture"`.
$handler Pflicht	(event: PictureInPictureEvent) => void		Callback-Funktion. `event.target` ist das Video, `event.pictureInPictureWindow` das gerade geschlossene `PictureInPictureWindow` (Breite/Höhe dann meist `0`).
$options	boolean \| AddEventListenerOptions	false	Optionen wie `once`, `capture`, `passive` oder `signal` (zum Entfernen über einen `AbortController`).

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Der Handler erhält ein PictureInPictureEvent.

Beispiele

PiP-Schaltfläche beim Verlassen zurücksetzen

const video = document.querySelector('#player');
const button = document.querySelector('#pip-button');

button.addEventListener('click', async () => {
  try {
    if (document.pictureInPictureElement === video) {
      await document.exitPictureInPicture();
    } else {
      await video.requestPictureInPicture();
    }
  } catch (err) {
    console.error('PiP fehlgeschlagen:', err);
  }
});

video.addEventListener('enterpictureinpicture', () => {
  button.textContent = 'Bild-in-Bild beenden';
});

video.addEventListener('leavepictureinpicture', (event) => {
  button.textContent = 'Bild-in-Bild öffnen';
  console.log('PiP verlassen:', event.target.id);
});

PiP verlassen: player

Über die on-Property: Video beim Schließen pausieren

const video = document.querySelector('video');

video.onleavepictureinpicture = () => {
  // Nutzer hat das PiP-Fenster geschlossen
  if (!video.paused) {
    video.pause();
    console.log('Wiedergabe pausiert');
  }
};

// Handler später wieder entfernen
// video.onleavepictureinpicture = null;

Wiedergabe pausiert

Resize-Listener aufräumen mit AbortController

const video = document.querySelector('video');
let controller;

video.addEventListener('enterpictureinpicture', ({ pictureInPictureWindow }) => {
  controller = new AbortController();
  pictureInPictureWindow.addEventListener('resize', (e) => {
    console.log(`PiP-Größe: ${e.target.width}x${e.target.height}`);
  }, { signal: controller.signal });
});

const onLeave = () => {
  controller?.abort(); // Resize-Listener entfernen
  console.log('Listener entfernt');
};

video.addEventListener('leavepictureinpicture', onLeave);

// Beim Abbau der Komponente:
// video.removeEventListener('leavepictureinpicture', onLeave);

Listener entfernt

// Wichtig · Fallstricke

Browser-Kompatibilität: Unterstützt in Chromium-Browsern (Chrome, Edge, Opera) und Safari ab 13.1. Firefox bietet zwar eine eigene Bild-in-Bild-Funktion an, implementiert aber die API nicht, dort wird das Ereignis also nie ausgelöst. Prüfe die Unterstützung vorher mit 'pictureInPictureEnabled' in document und document.pictureInPictureEnabled.
Das Ereignis wird auch ausgelöst, wenn ein anderes Video in den PiP-Modus wechselt, denn es kann immer nur ein Element gleichzeitig im PiP-Modus sein. Das zuvor aktive Video erhält dann leavepictureinpicture.
Wird das Video aus dem DOM entfernt, während es im PiP-Modus ist, verlässt der Browser den Modus automatisch. Den Handler also nicht zu früh entfernen, wenn du dort aufräumen willst.
Innerhalb des Handlers ist document.pictureInPictureElement bereits null (bzw. das neue PiP-Element).
Die Eigenschaften width/height des übergebenen PictureInPictureWindow sind nach dem Schließen 0, sie sind hier also nicht aussagekräftig.
Die neuere Document Picture-in-Picture API (documentPictureInPicture) nutzt dieses Ereignis nicht, stattdessen wird dort ein pagehide-Ereignis am PiP-Fenster ausgelöst.

Siehe auch

HTMLVideoElement: enterpictureinpicture HTMLVideoElement.requestPictureInPicture() Document.exitPictureInPicture() Document.pictureInPictureElement Document.pictureInPictureEnabled PictureInPictureEvent PictureInPictureWindow HTMLVideoElement