DocumentPictureInPicture.window — Eigenschaft · JavaScript-Referenz

Signatur

DocumentPictureInPicture.window

Beschreibung

Die schreibgeschützte Eigenschaft window des Objekts documentPictureInPicture verweist auf das Window des Picture-in-Picture-Fensters, das gerade geöffnet ist. Das ist derselbe Browsing-Kontext, den das Promise von documentPictureInPicture.requestWindow() liefert.

Nützlich ist die Eigenschaft vor allem dann, wenn Sie an anderer Stelle im Code auf das PiP-Fenster zugreifen wollen, ohne sich die Referenz aus requestWindow() selbst merken zu müssen. So können Sie prüfen, ob ein Fenster offen ist, dessen DOM ändern (zum Beispiel Steuerelemente eines Videoplayers aktualisieren) oder es mit window.close() schließen.

Ist kein Document-PiP-Fenster geöffnet, ist der Wert null. Pro Top-Level-Kontext gibt es höchstens ein solches Fenster. Ein erneuter Aufruf von requestWindow() schließt das vorhandene Fenster und öffnet ein neues. Anders als beim Video-PiP (HTMLVideoElement.requestPictureInPicture()) darf das Fenster beliebiges HTML enthalten.

Rückgabewert

Typ

Window | null

Beschreibung

Das Window-Objekt des geöffneten Picture-in-Picture-Fensters oder null, wenn keines offen ist.

Beispiele

PiP-Fenster öffnen und über die Eigenschaft wieder darauf zugreifen

const openBtn = document.querySelector('#pip-open');

openBtn.addEventListener('click', async () => {
  // requestWindow() setzt eine Nutzeraktion voraus
  await documentPictureInPicture.requestWindow({ width: 360, height: 200 });

  // Dasselbe Fenster über die Eigenschaft ansprechen
  const pipWin = documentPictureInPicture.window;
  const p = pipWin.document.createElement('p');
  p.textContent = 'Hallo aus dem PiP-Fenster!';
  pipWin.document.body.append(p);

  console.log(pipWin === documentPictureInPicture.window);
});

true

Prüfen, ob ein PiP-Fenster offen ist, und es schließen

const closePip = () => {
  const pipWin = documentPictureInPicture.window;
  if (pipWin) {
    pipWin.close();
    console.log('PiP-Fenster geschlossen');
  } else {
    console.log('Kein PiP-Fenster offen');
  }
};

document.querySelector('#pip-close').addEventListener('click', closePip);

Kein PiP-Fenster offen

Player ins PiP-Fenster verschieben und beim Schließen zurückholen

const player = document.querySelector('#player');
const container = document.querySelector('#player-container');

document.querySelector('#pip').addEventListener('click', async () => {
  if (!('documentPictureInPicture' in window)) {
    console.warn('Document PiP wird nicht unterstützt');
    return;
  }

  await documentPictureInPicture.requestWindow();
  const pipWin = documentPictureInPicture.window;

  // Stylesheets übernehmen
  for (const sheet of document.styleSheets) {
    try {
      const css = [...sheet.cssRules].map((r) => r.cssText).join('');
      const style = pipWin.document.createElement('style');
      style.textContent = css;
      pipWin.document.head.append(style);
    } catch {
      // Stylesheet von fremder Herkunft: als <link> übernehmen
      const link = pipWin.document.createElement('link');
      link.rel = 'stylesheet';
      link.href = sheet.href;
      pipWin.document.head.append(link);
    }
  }

  pipWin.document.body.append(player);

  // Beim Schließen den Player zurückholen
  pipWin.addEventListener('pagehide', () => {
    container.append(player);
  });
});

// Wichtig · Fallstricke

Kompatibilität: Die Document Picture-in-Picture API ist experimentell und nur in Chromium-Browsern verfügbar (Chrome/Edge ab 116, nur Desktop). Prüfen Sie die Unterstützung mit 'documentPictureInPicture' in window.
Die API steht nur in sicheren Kontexten (HTTPS) und nur im Top-Level-Fenster zur Verfügung, nicht in iframes.
Der Wert ist null, solange kein Fenster geöffnet ist. Deshalb vor jedem Zugriff prüfen, denn sonst droht ein TypeError.
Das PiP-Fenster startet mit einem leeren Dokument. Stylesheets werden nicht automatisch übernommen und müssen kopiert werden.
Die Referenz wird ungültig, sobald Nutzer das Fenster schließen. Auf das Ereignis pagehide des PiP-Fensters reagieren, um Elemente zurückzuverschieben.
Die Eigenschaft ist schreibgeschützt. Eine Zuweisung hat keine Wirkung.

Siehe auch

Window DocumentPictureInPictureEvent.window Document.pictureInPictureElement Document.pictureInPictureEnabled Window.documentPictureInPicture