Signatur
Beschreibung
Die Eigenschaft window eines DocumentPictureInPictureEvent verweist auf die Window-Instanz des Browsing-Kontexts im Picture-in-Picture-Fenster (PiP-Fenster). Das Ereignis wird als enter-Ereignis auf dem globalen Objekt window.documentPictureInPicture ausgelöst, sobald ein PiP-Fenster über documentPictureInPicture.requestWindow() geöffnet wurde.
Nützlich ist die Eigenschaft vor allem dann, wenn das Öffnen des Fensters und die Reaktion darauf an verschiedenen Stellen im Code passieren, zum Beispiel in einem zentralen Modul, das Stylesheets kopiert, Analyse-Code einhängt oder auf das Schließen des PiP-Fensters (pagehide) reagiert, ohne selbst requestWindow() aufgerufen zu haben.
Das zurückgegebene Objekt ist ein vollwertiges Window mit eigenem document. Es gehört zum selben Ursprung wie das öffnende Dokument. Deshalb können Sie DOM-Knoten direkt hineinverschieben (append()) und Ereignis-Listener registrieren. Den Wert selbst können Sie aber nicht neu zuweisen.
Rückgabewert
Window-Objekt des geöffneten Document-Picture-in-Picture-Fensters. Es ist identisch mit dem Wert, mit dem das Promise von requestWindow() erfüllt wird.Beispiele
Auf das Öffnen eines PiP-Fensters reagieren
if ('documentPictureInPicture' in window) {
documentPictureInPicture.addEventListener('enter', (event) => {
const pipWindow = event.window;
console.log('PiP-Fenster geöffnet:', pipWindow.innerWidth, 'x', pipWindow.innerHeight);
// Aufräumen, wenn das PiP-Fenster geschlossen wird
pipWindow.addEventListener('pagehide', () => {
console.log('PiP-Fenster geschlossen');
});
});
}Stylesheets zentral in das PiP-Fenster kopieren
const copyStyles = (targetWindow) => {
for (const sheet of document.styleSheets) {
try {
const css = [...sheet.cssRules].map((rule) => rule.cssText).join('\n');
const style = targetWindow.document.createElement('style');
style.textContent = css;
targetWindow.document.head.append(style);
} catch {
// Fremd-Stylesheets (CORS) per <link> übernehmen
const link = targetWindow.document.createElement('link');
link.rel = 'stylesheet';
link.href = sheet.href;
targetWindow.document.head.append(link);
}
}
};
documentPictureInPicture.addEventListener('enter', (event) => {
copyStyles(event.window);
});Player öffnen und im enter-Handler befüllen
const player = document.querySelector('#player');
const container = player.parentElement;
documentPictureInPicture.addEventListener('enter', ({ window: pipWindow }) => {
pipWindow.document.body.append(player);
pipWindow.addEventListener('pagehide', () => {
container.append(player); // Player zurückholen
});
});
document.querySelector('#pip-button').addEventListener('click', async () => {
// requestWindow() erfordert eine Nutzeraktion
await documentPictureInPicture.requestWindow({ width: 400, height: 300 });
});// Wichtig · Fallstricke
- Kompatibilität: Die Document Picture-in-Picture API ist experimentell und nur in Chromium-Browsern ab Version 116 verfügbar (Desktop). Prüfen Sie die Unterstützung mit
'documentPictureInPicture' in window. - Die API steht nur in sicheren Kontexten (HTTPS) bereit.
requestWindow()braucht zudem eine vorübergehende Nutzeraktivierung, etwa einen Klick. - Gleichzeitig kann nur ein PiP-Fenster pro Tab offen sein. Ein erneuter Aufruf von
requestWindow()schließt das bestehende Fenster. - Das neue Fenster startet ohne Stylesheets. CSS müssen Sie selbst kopieren.
- Speichern Sie keine dauerhaften Verweise auf
event.window, ohne sie beimpagehide-Ereignis wieder freizugeben. Sonst hängen Listener an einem geschlossenen Fenster. - Nicht zu verwechseln mit dem globalen
window: Destrukturieren Sie besser mit Umbenennung ({ window: pipWindow }), damit das globale Objekt nicht überdeckt wird.