PictureInPictureWindow: resize — Ereignis · JavaScript-Referenz

Signatur

pipWindow.addEventListener("resize", handler)

Beschreibung

Das resize-Ereignis gehört zum Interface PictureInPictureWindow. Ein solches Objekt bekommt man als Erfüllungswert des Promises von HTMLVideoElement.requestPictureInPicture() oder über die Eigenschaft pictureInPictureWindow des enterpictureinpicture-Ereignisses. Ändert der Nutzer die Größe des schwebenden Fensters, feuert das Ereignis. Die neuen Maße stehen dann in event.target.width und event.target.height.

Einen Handler meldet man entweder mit pipWindow.addEventListener("resize", handler) an oder über die Eigenschaft pipWindow.onresize = handler. Das Ereignis ist ein einfaches Event (in der Spezifikation PictureInPictureEvent-kompatibel). Es kann nicht abgebrochen werden und steigt nicht im DOM auf (kein Bubbling).

Typische Einsatzfälle:

Adaptives Streaming: Bei kleinem Fenster auf eine niedrigere Videoauflösung wechseln, um Bandbreite zu sparen.
Statistik: Erfassen, welche Fenstergrößen die Nutzer bevorzugen.
Canvas-/MediaStream-Quellen: Die Auflösung eines gerenderten Streams an die tatsächliche Fenstergröße anpassen.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignistyp, hier immer `"resize"`.
$handler Pflicht	(event: Event) => void		Callback-Funktion. `event.target` ist das `PictureInPictureWindow` mit den aktuellen Werten `width` und `height`.
$options	boolean \| AddEventListenerOptions	false	Optionale Listener-Optionen wie `once` oder `signal`, z. B. zum Abmelden per `AbortController`.

Beispiele

Fenstergröße mit addEventListener überwachen

const video = document.querySelector('video');
const button = document.querySelector('#pip-button');

button.addEventListener('click', async () => {
  try {
    const pipWindow = await video.requestPictureInPicture();
    console.log(`Start: ${pipWindow.width}×${pipWindow.height}`);

    pipWindow.addEventListener('resize', (event) => {
      const { width, height } = event.target;
      console.log(`Neue PiP-Größe: ${width}×${height}`);
    });
  } catch (err) {
    console.error('Bild-im-Bild nicht möglich:', err);
  }
});

Start: 400×225 Neue PiP-Größe: 640×360

Videoqualität an die Fenstergröße anpassen (onresize)

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

// Wählt eine passende Qualitätsstufe (Beispielfunktion)
const pickQuality = (width) => {
  if (width < 400) return '360p';
  if (width < 800) return '720p';
  return '1080p';
};

video.addEventListener('enterpictureinpicture', (event) => {
  const pipWindow = event.pictureInPictureWindow;

  pipWindow.onresize = () => {
    const quality = pickQuality(pipWindow.width);
    console.log(`Wechsle auf ${quality} (Breite ${pipWindow.width}px)`);
    // hier z. B. player.setQuality(quality) aufrufen
  };
});

video.addEventListener('leavepictureinpicture', () => {
  console.log('Bild-im-Bild beendet');
});

Wechsle auf 720p (Breite 512px) Bild-im-Bild beendet

Listener entprellen und sauber wieder entfernen

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

const debounce = (fn, ms) => {
  let timer;
  return (...args) => {
    clearTimeout(timer);
    timer = setTimeout(() => fn(...args), ms);
  };
};

const onPipResize = debounce((event) => {
  const { width, height } = event.target;
  console.log(`Endgültige Größe: ${width}×${height}`);
}, 250);

video.addEventListener('enterpictureinpicture', (event) => {
  const pipWindow = event.pictureInPictureWindow;
  pipWindow.addEventListener('resize', onPipResize);

  video.addEventListener('leavepictureinpicture', () => {
    pipWindow.removeEventListener('resize', onPipResize);
    console.log('resize-Listener entfernt');
  }, { once: true });
});

Endgültige Größe: 720×405 resize-Listener entfernt

// Wichtig · Fallstricke

Browserunterstützung: Die Picture-in-Picture-API für Videos gibt es nur in Chromium-Browsern (Chrome, Edge, Opera). Firefox hat zwar eine eigene Bild-im-Bild-Funktion in der Oberfläche, stellt die API aber nicht bereit. Safari hat stattdessen die proprietäre API webkitSetPresentationMode. Deshalb vorher prüfen, ob document.pictureInPictureEnabled gesetzt ist bzw. 'requestPictureInPicture' in HTMLVideoElement.prototype gilt.
Das Ereignis kann während einer Größenänderung mehrfach hintereinander feuern. Aufwendige Reaktionen wie ein Qualitätswechsel sollten daher entprellt werden.
Nach dem Verlassen des Bild-im-Bild-Modus sind width und height 0, und es kommen keine weiteren resize-Ereignisse. Für jede neue PiP-Sitzung liefert der Browser unter Umständen ein neues PictureInPictureWindow-Objekt, auf dem der Listener neu registriert werden muss.
Nicht mit window-resize verwechseln: Das Hauptfenster bekommt bei Größenänderungen des PiP-Fensters kein Ereignis.
Der Aufruf von requestPictureInPicture() braucht eine Nutzeraktion (z. B. einen Klick) und kann durch die Permissions-Policy picture-in-picture blockiert werden, etwa in iframes.
Für beliebige HTML-Inhalte statt Videos gibt es die neuere Document Picture-in-Picture API (documentPictureInPicture). Dort nutzt man das normale resize-Ereignis des PiP-window.

Siehe auch

Window: resize VisualViewport: resize DocumentPictureInPicture: enter HTMLVideoElement: resize MediaRecorder: resume