Document.exitPictureInPicture() — Methode · JavaScript-Referenz

Signatur

Document.prototype.exitPictureInPicture()

Beschreibung

Die Methode document.exitPictureInPicture() fordert den Browser auf, das Video, das gerade im Bild-in-Bild-Fenster (Picture-in-Picture, PiP) schwebt, wieder in die Seite zurückzuholen. Das PiP-Fenster wird geschlossen und das Video wird wieder an seiner ursprünglichen Stelle im Dokument angezeigt.

Sie ist das Gegenstück zu HTMLVideoElement.prototype.requestPictureInPicture(). Welches Element gerade im PiP-Modus ist, verrät document.pictureInPictureElement. Ist dieser Wert null, gibt es nichts zu beenden, und das Promise wird mit einer InvalidStateError-DOMException abgelehnt.

Typische Einsatzfälle sind ein eigener Umschalt-Button im Videoplayer, das automatische Beenden beim Wechsel zu einem anderen Video oder das Aufräumen beim Verlassen einer Single-Page-App-Ansicht. Nach erfolgreichem Beenden löst das Video-Element das Ereignis leavepictureinpicture aus.

Rückgabewert

Typ

Promise<void>

Beschreibung

Ein Promise, das mit undefined erfüllt wird, sobald der Browser den Bild-in-Bild-Modus beendet hat. Es wird mit InvalidStateError abgelehnt, wenn kein Element im PiP-Modus ist.

Beispiele

PiP-Modus per Button umschalten

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

toggleBtn.addEventListener('click', async () => {
  try {
    if (document.pictureInPictureElement) {
      // Aktives PiP-Fenster schließen
      await document.exitPictureInPicture();
      console.log('Bild-in-Bild beendet');
    } else if (document.pictureInPictureEnabled) {
      await video.requestPictureInPicture();
      console.log('Bild-in-Bild gestartet');
    }
  } catch (err) {
    console.error(`PiP-Fehler: ${err.name} – ${err.message}`);
  }
});

Bild-in-Bild gestartet Bild-in-Bild beendet

Sicheres Beenden mit Prüfung und Fehlerbehandlung

const leavePip = async () => {
  if (!('exitPictureInPicture' in document)) {
    console.warn('Picture-in-Picture-API wird nicht unterstützt');
    return false;
  }
  if (!document.pictureInPictureElement) {
    return false; // nichts zu tun, vermeidet InvalidStateError
  }
  await document.exitPictureInPicture();
  return true;
};

// z. B. beim Routenwechsel in einer SPA
window.addEventListener('pagehide', () => {
  leavePip().catch(console.error);
});

Auf das Ende des PiP-Modus reagieren

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

video.addEventListener('leavepictureinpicture', () => {
  console.log('Video ist zurück in der Seite');
  video.pause();
});

// Beim Wechsel zu einem anderen Video PiP beenden
const loadNextVideo = async (src) => {
  if (document.pictureInPictureElement === video) {
    await document.exitPictureInPicture();
  }
  video.src = src;
  await video.play();
};

loadNextVideo('/media/folge-2.mp4');

Video ist zurück in der Seite

// Wichtig · Fallstricke

InvalidStateError: Ist document.pictureInPictureElement null, wird das Promise abgelehnt. Vorher prüfen oder den Fehler mit catch abfangen.
Browser-Kompatibilität: Unterstützt in Chromium-Browsern (Chrome, Edge, Opera) und Safari ab 13.1. Firefox bietet zwar einen eigenen PiP-Knopf, implementiert die Picture-in-Picture-API aber nicht – daher immer per 'exitPictureInPicture' in document auf Unterstützung prüfen.
Anders als requestPictureInPicture() braucht das Beenden keine Nutzeraktivierung (User Gesture); es kann also auch programmatisch aufgerufen werden, z. B. beim Seitenwechsel.
Die Methode gilt nur für Video-PiP. Für beliebige HTML-Inhalte gibt es die separate Document Picture-in-Picture API (documentPictureInPicture.requestWindow(), derzeit nur Chromium); deren Fenster schließt man über window.close() des PiP-Fensters.
Das Schließen durch den Nutzer (X-Knopf im PiP-Fenster) löst ebenfalls leavepictureinpicture aus – Aufräumlogik daher im Ereignis statt nur nach dem await platzieren.

Siehe auch

Document.exitPointerLock() Document.exitFullscreen() Document.releaseCapture() Document.createAttribute() Document.elementFromPoint()