Signatur
Beschreibung
Die Eigenschaft pictureInPictureWindow des PictureInPictureEvent-Interfaces liefert das PictureInPictureWindow-Objekt, also das schwebende Bild-im-Bild-Fenster, zu dem das Ereignis gehört. Sie steht in den Ereignissen enterpictureinpicture und leavepictureinpicture zur Verfügung, die an einem HTMLVideoElement ausgelöst werden.
Praktisch nutzt man die Eigenschaft vor allem im enterpictureinpicture-Handler. Dort liest man die aktuelle Fenstergröße über width und height aus oder registriert einen resize-Listener, um z. B. eine passende Videoqualität zu wählen oder Statistiken zu erfassen. So muss man das Fenster nicht in einer eigenen Variable speichern, die man aus dem Promise von requestPictureInPicture() erhält.
Der Wert wird beim Erzeugen des Ereignisses festgelegt und lässt sich danach nicht mehr ändern. Beim Konstruktor new PictureInPictureEvent(type, options) ist options.pictureInPictureWindow ein Pflichtfeld.
Rückgabewert
width und height sowie das Ereignis resize.Beispiele
Fenstergröße beim Öffnen des Bild-im-Bild-Modus auslesen
const video = document.querySelector('video');
video.addEventListener('enterpictureinpicture', (event) => {
const pipWindow = event.pictureInPictureWindow;
console.log(`PiP-Fenster: ${pipWindow.width}×${pipWindow.height}`);
});
document.querySelector('#pip-button').addEventListener('click', async () => {
try {
await video.requestPictureInPicture();
} catch (err) {
console.error('Bild-im-Bild nicht möglich:', err);
}
});Videoqualität an die Fenstergröße anpassen und Listener aufräumen
const video = document.querySelector('video');
const chooseQuality = (width) => (width > 640 ? '720p' : width > 320 ? '480p' : '240p');
const onResize = (e) => {
const { width } = e.target;
console.log('Neue Qualität:', chooseQuality(width));
};
video.addEventListener('enterpictureinpicture', (event) => {
event.pictureInPictureWindow.addEventListener('resize', onResize);
});
video.addEventListener('leavepictureinpicture', (event) => {
// Listener am selben Fensterobjekt wieder entfernen
event.pictureInPictureWindow.removeEventListener('resize', onResize);
console.log('Bild-im-Bild beendet');
});Ereignis selbst erzeugen (z. B. für Tests)
const video = document.querySelector('video');
video.addEventListener('enterpictureinpicture', async (event) => {
const win = event.pictureInPictureWindow;
// Ein eigenes Ereignis mit demselben Fenster weiterreichen
const copy = new PictureInPictureEvent('enterpictureinpicture', {
pictureInPictureWindow: win
});
console.log(copy.pictureInPictureWindow === win);
});// Wichtig · Fallstricke
- Browser-Kompatibilität: Die Picture-in-Picture-API für Videos wird von Chromium-Browsern und Safari unterstützt. Firefox bietet zwar eine eigene Bild-im-Bild-Funktion in der Oberfläche an, implementiert die API aber nicht. Vorher mit
'pictureInPictureEnabled' in documentunddocument.pictureInPictureEnabledprüfen. - Nach
leavepictureinpictureist das Fenster geschlossen.widthundheightliefern dann0. Werte, die man später noch braucht, deshalb schon beim Öffnen speichern. - Die Eigenschaft ist schreibgeschützt. Eine Zuweisung wird still ignoriert bzw. löst im Strict Mode keinen Fehler aus, ändert den Wert aber nicht.
- Nicht verwechseln mit der Document Picture-in-Picture API (
documentPictureInPicture.requestWindow()). Diese liefert ein echtesWindow-Objekt und verwendetDocumentPictureInPictureEvent.window. requestPictureInPicture()braucht eine Nutzeraktion (z. B. einen Klick). Sonst wird das Promise mitNotAllowedErrorabgelehnt, und es wird kein Ereignis ausgelöst.