Signatur
Beschreibung
Der Konstruktor DocumentPictureInPictureEvent() legt eine neue Instanz des Interfaces DocumentPictureInPictureEvent an. Der Browser löst dieses Ereignis selbst als enter-Event am Objekt window.documentPictureInPicture aus, sobald über documentPictureInPicture.requestWindow() ein Bild-im-Bild-Fenster geöffnet wurde. Über die Eigenschaft event.window erreicht man dann das Window-Objekt dieses Fensters.
Den Konstruktor ruft man selbst nur selten auf. Nützlich ist er vor allem in Unit-Tests und Mocks: Damit lässt sich prüfen, ob die eigene Logik für das enter-Ereignis richtig reagiert, ohne dass ein echtes Bild-im-Bild-Fenster aufgehen muss. Genauso eignet er sich für eigene Ereignis-Busse, die dieselbe Ereignis-Form nachbilden.
Die Pflichtangabe im Options-Objekt ist window. Dazu kommen die üblichen Felder aus EventInit (bubbles, cancelable, composed). Selbst erzeugte Ereignisse haben immer isTrusted === false.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $type Pflicht | string | Name des Ereignisses. Die Spezifikation verwendet dafür "enter". |
|
| $options Pflicht | object | Das Initialisierungsobjekt. Es erbt die Felder von EventInit und ergänzt diese Einstellungen:
|
Rückgabewert
DocumentPictureInPictureEvent. Die schreibgeschützte Eigenschaft window verweist auf das übergebene Fenster.Beispiele
Ereignis manuell erzeugen und auslesen
// Zu Testzwecken steht das aktuelle Fenster für das Bild-im-Bild-Fenster
const event = new DocumentPictureInPictureEvent('enter', {
window: window,
});
console.log(event.type); // Ereignisname
console.log(event.window === window); // verweist auf das übergebene Fenster
console.log(event.isTrusted); // selbst erzeugt, also nicht vertrauenswürdigAuf das echte enter-Ereignis reagieren
const button = document.querySelector('#pip-button');
const player = document.querySelector('#player');
// Der Browser löst "enter" selbst aus, sobald das Fenster offen ist
documentPictureInPicture.addEventListener('enter', (event) => {
const pipWindow = event.window;
console.log('Bild-im-Bild geöffnet:', pipWindow.innerWidth, 'x', pipWindow.innerHeight);
// Beim Schließen den Player in die Hauptseite zurückholen
pipWindow.addEventListener('pagehide', () => {
document.body.append(player);
});
});
button.addEventListener('click', async () => {
// requestWindow() braucht eine Nutzergeste (hier der Klick)
const pipWindow = await documentPictureInPicture.requestWindow({ width: 400, height: 240 });
pipWindow.document.body.append(player);
});Handler im Test mit einem simulierten Ereignis prüfen
// Die Logik, die getestet werden soll
const onEnter = (event) => {
event.window.document.title = 'Mini-Player';
return event.window.document.title;
};
// Ein Iframe dient als Ersatz für das Bild-im-Bild-Fenster
const iframe = document.createElement('iframe');
document.body.append(iframe);
const fakeEvent = new DocumentPictureInPictureEvent('enter', {
window: iframe.contentWindow,
});
console.log(onEnter(fakeEvent));
iframe.remove();// Wichtig · Fallstricke
- Experimentell: Die Document Picture-in-Picture API gibt es bisher nur in Chromium-Browsern ab Version 116, und zwar nur auf dem Desktop. Vor der Nutzung sollte man prüfen, ob die API vorhanden ist, z. B. mit
'documentPictureInPicture' in windowodertypeof DocumentPictureInPictureEvent === 'function'. - Fehlt
windowim Options-Objekt, wirft der Konstruktor einenTypeError, denn das Feld ist Pflicht. - Ein selbst erzeugtes Ereignis öffnet kein Bild-im-Bild-Fenster. Das kann nur
documentPictureInPicture.requestWindow(), und dafür braucht es eine Nutzergeste sowie einen sicheren Kontext (HTTPS). - Selbst ausgelöste Ereignisse haben
isTrusted === false. Code, der aus Sicherheitsgründen aufisTrustedprüft, reagiert deshalb nicht darauf. - Pro Seite kann nur ein Bild-im-Bild-Fenster offen sein. Ein erneuter Aufruf von
requestWindow()schließt das bisherige Fenster.