DocumentPictureInPictureEvent — Schnittstelle · JavaScript-Referenz

Signatur

interface DocumentPictureInPictureEvent extends Event

Beschreibung

Das Interface DocumentPictureInPictureEvent gehört zur Document Picture-in-Picture API. Mit dieser API lässt sich beliebiger HTML-Inhalt, nicht nur ein <video>-Element, in einem immer sichtbaren Bild-im-Bild-Fenster anzeigen. Sobald ein solches Fenster mit documentPictureInPicture.requestWindow() geöffnet wird, löst das globale Objekt window.documentPictureInPicture das Ereignis enter aus. Das zugehörige Ereignisobjekt ist eine Instanz von DocumentPictureInPictureEvent.

Neben den geerbten Eigenschaften von Event stellt das Interface nur eine eigene, schreibgeschützte Eigenschaft bereit: window. Sie verweist auf das Window-Objekt des neuen PiP-Fensters. Damit können Sie an zentraler Stelle auf das Öffnen reagieren, etwa um Stylesheets zu kopieren, Ereignis-Listener zu registrieren oder Analyse-Daten zu erfassen. Das funktioniert unabhängig davon, an welcher Stelle im Code requestWindow() aufgerufen wurde.

Ein Konstruktor new DocumentPictureInPictureEvent(type, options) ist vorhanden. In der Praxis braucht man ihn aber kaum. Er dient vor allem Tests oder dem Nachstellen des Ereignisses mit dispatchEvent(). Das Pflichtfeld options.window muss dabei ein Window-Objekt sein.

Parameter

Name	Typ	Beschreibung
$type Pflicht	string	Name des Ereignisses (Konstruktor). Für die API selbst immer `"enter"`.
$options Pflicht	object	Initialisierungsobjekt. Es enthält die Felder von `EventInit` (`bubbles`, `cancelable`, `composed`) und das Pflichtfeld `window`.
$options.window Pflicht	Window	Das `Window`-Objekt, das später über die Eigenschaft `event.window` zurückgegeben wird.

Rückgabewert

Typ

DocumentPictureInPictureEvent

Beschreibung

Beim Konstruktor eine neue Ereignisinstanz. Die Eigenschaft window liefert ein Window: das Fenster-Objekt des geöffneten Picture-in-Picture-Fensters.

Beispiele

Auf das Öffnen des PiP-Fensters reagieren (addEventListener)

if ('documentPictureInPicture' in window) {
  documentPictureInPicture.addEventListener('enter', (event) => {
    const pipWindow = event.window;
    console.log('PiP geöffnet:', pipWindow.innerWidth, 'x', pipWindow.innerHeight);

    // Aufräumen, wenn das PiP-Fenster geschlossen wird
    pipWindow.addEventListener('pagehide', () => {
      console.log('PiP-Fenster geschlossen');
    });
  });
}

// Muss durch eine Benutzeraktion ausgelöst werden
document.querySelector('#pip-btn').addEventListener('click', async () => {
  await documentPictureInPicture.requestWindow({ width: 400, height: 300 });
});

PiP geöffnet: 400 x 300

Stylesheets zentral ins PiP-Fenster kopieren

const copyStyles = (targetWindow) => {
  for (const sheet of document.styleSheets) {
    try {
      const css = [...sheet.cssRules].map((r) => r.cssText).join('\n');
      const style = targetWindow.document.createElement('style');
      style.textContent = css;
      targetWindow.document.head.append(style);
    } catch {
      // Fremd-Origin-Stylesheet: als <link> einbinden
      const link = targetWindow.document.createElement('link');
      link.rel = 'stylesheet';
      link.href = sheet.href;
      targetWindow.document.head.append(link);
    }
  }
};

documentPictureInPicture.onenter = (event) => {
  copyStyles(event.window);
};

document.querySelector('#player-btn').addEventListener('click', async () => {
  const pipWindow = await documentPictureInPicture.requestWindow();
  pipWindow.document.body.append(document.querySelector('#player'));
});

Ereignis für Tests manuell erzeugen

const handler = (event) => {
  console.log(event instanceof DocumentPictureInPictureEvent, event.window === window);
};

documentPictureInPicture.addEventListener('enter', handler);

const fakeEvent = new DocumentPictureInPictureEvent('enter', { window });
documentPictureInPicture.dispatchEvent(fakeEvent);

// Listener wieder entfernen
documentPictureInPicture.removeEventListener('enter', handler);

true true

// Wichtig · Fallstricke

Browserunterstützung: Die API gibt es bisher nur in Chromium-basierten Desktop-Browsern (ab Chrome/Edge 116). Firefox und Safari unterstützen sie nicht. Prüfen Sie deshalb vorher mit 'documentPictureInPicture' in window, ob sie verfügbar ist.
Sicherer Kontext: Die API funktioniert nur über HTTPS bzw. localhost.
Benutzeraktion: requestWindow() braucht eine vorherige Benutzeraktion (transient activation), etwa einen Klick. Sonst wird ein NotAllowedError ausgelöst und kein enter-Ereignis gefeuert.
Das enter-Ereignis wird auf window.documentPictureInPicture ausgelöst, nicht auf window oder document. Ein Gegenstück wie „leave“ gibt es nicht. Um das Schließen zu erkennen, lauschen Sie auf pagehide am PiP-Fenster (event.window).
Das PiP-Fenster startet mit einem leeren Dokument und übernimmt keine Stylesheets. Diese müssen Sie selbst kopieren.
Pro Seite kann immer nur ein PiP-Fenster offen sein. Ein neuer Aufruf von requestWindow() schließt das bestehende Fenster.
Die Spezifikation ist noch ein Entwurf der WICG und kann sich ändern.

Siehe auch

Window Event DocumentPictureInPicture PictureInPictureEvent PictureInPictureWindow