new PictureInPictureEvent() — Methode · JavaScript-Referenz

Signatur

new PictureInPictureEvent(type, options)

Beschreibung

Der Konstruktor PictureInPictureEvent() legt ein neues Ereignisobjekt vom Typ PictureInPictureEvent an. Der Browser erzeugt solche Ereignisse normalerweise selbst: Er feuert enterpictureinpicture an einem <video>-Element, sobald es in den Bild-im-Bild-Modus wechselt, und leavepictureinpicture, wenn es den Modus verlässt.

Den Konstruktor ruft man selbst vor allem dann auf, wenn man solche Ereignisse synthetisch auslösen will, etwa in Unit-Tests, bei der Simulation von Zustandswechseln oder um eigene Komponenten über einen PiP-Wechsel zu informieren. Anders als beim allgemeinen Event-Konstruktor ist hier die Eigenschaft pictureInPictureWindow im Optionsobjekt Pflicht. Sie muss auf ein echtes PictureInPictureWindow-Objekt verweisen.

Ein PictureInPictureWindow kann man nicht selbst konstruieren. Man bekommt es nur als Ergebnis von HTMLVideoElement.prototype.requestPictureInPicture() oder aus einem echten PiP-Ereignis. Synthetische Ereignisse setzen also in der Praxis voraus, dass zuvor ein echtes PiP-Fenster geöffnet wurde.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Ereignisses, beim Browser üblicherweise `"enterpictureinpicture"`, `"leavepictureinpicture"` oder `"resize"`. Eigene Namen sind erlaubt.
$options Pflicht	PictureInPictureEventInit		Objekt mit den Eigenschaften aus `EventInit` (`bubbles`, `cancelable`, `composed`, jeweils Standardwert `false`) und dem Pflichtfeld `pictureInPictureWindow`, einem `PictureInPictureWindow`.

Rückgabewert

Typ

PictureInPictureEvent

Beschreibung

Ein neues PictureInPictureEvent. Über seine Eigenschaft pictureInPictureWindow erreicht man das zugehörige PiP-Fenster.

Beispiele

Echtes Ereignis abfangen und Fenstergröße auslesen

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

video.addEventListener('enterpictureinpicture', (event) => {
  const pipWindow = event.pictureInPictureWindow;
  console.log(`PiP gestartet: ${pipWindow.width}x${pipWindow.height}`);
});

document.querySelector('#pip-button').addEventListener('click', async () => {
  if (document.pictureInPictureEnabled) {
    await video.requestPictureInPicture();
  }
});

PiP gestartet: 400x225

Synthetisches Ereignis mit echtem PiP-Fenster erzeugen

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

const simulateEnter = async () => {
  // Das PiP-Fenster lässt sich nur so erhalten (Nutzergeste nötig)
  const pipWindow = await video.requestPictureInPicture();

  const event = new PictureInPictureEvent('pip-status', {
    pictureInPictureWindow: pipWindow,
    bubbles: true
  });

  console.log(event.type, event.pictureInPictureWindow === pipWindow);
  video.dispatchEvent(event);
};

document.addEventListener('pip-status', () => console.log('Status-Ereignis empfangen'));
document.querySelector('#pip-button').addEventListener('click', simulateEnter);

pip-status true Status-Ereignis empfangen

Fehlendes Pflichtfeld erzeugt TypeError

try {
  new PictureInPictureEvent('enterpictureinpicture', {});
} catch (err) {
  console.log(err.name);
}

TypeError

// Wichtig · Fallstricke

Pflichtfeld: Wenn pictureInPictureWindow fehlt oder kein echtes PictureInPictureWindow ist, wirft der Konstruktor einen TypeError.
Ein PictureInPictureWindow lässt sich nicht selbst erzeugen. In Tests ohne echtes Video muss man stattdessen ein einfaches Event oder CustomEvent verwenden oder das Objekt nachbilden (mocken).
Synthetische Ereignisse haben isTrusted === false. Außerdem lösen sie keine Aktion im Browser aus. Das Video wechselt dadurch also nicht in den PiP-Modus.
Für requestPictureInPicture() braucht es eine Nutzergeste. Außerdem muss das Video Metadaten geladen haben und darf nicht das Attribut disablePictureInPicture tragen.
Kompatibilität: Unterstützt in Chromium-Browsern und Safari, nicht in Firefox. Firefox bietet zwar eine eigene PiP-Schaltfläche an, aber nicht diese API. Vorab prüfen mit 'PictureInPictureEvent' in window bzw. document.pictureInPictureEnabled.

Siehe auch

new DocumentFragment() new DocumentPictureInPictureEvent() new InterestEvent() new PageTransitionEvent() new PeriodicSyncEvent()