HTMLVideoElement: resize — Ereignis · JavaScript-Referenz

Signatur

videoElement.addEventListener("resize", handler)

Beschreibung

Das resize-Ereignis eines HTMLVideoElement meldet eine Änderung der eigentlichen Auflösung des Videos, also der Werte in videoWidth und videoHeight. Mit der Größe des Elements auf der Seite (CSS-Box) hat es nichts zu tun. Dafür nimmt man ResizeObserver.

Ausgelöst wird das Ereignis vor allem in diesen Fällen:

Die Metadaten wurden zum ersten Mal geladen und die Abmessungen sind jetzt bekannt (vorher waren sie 0).
Bei adaptivem Streaming (HLS/DASH über Media Source Extensions) wechselt die Qualitätsstufe.
Bei WebRTC- oder Kamera-Streams (srcObject mit einem MediaStream) ändert sich die Auflösung, z. B. bei schwacher Bandbreite oder wenn das Gerät gedreht wird.

Registrieren kannst du das Ereignis mit addEventListener("resize", handler) oder über die Eigenschaft onresize. Es blubbert nicht (bubbles: false), lässt sich nicht abbrechen und ist ein einfaches Event ohne zusätzliche Eigenschaften. Die neuen Werte liest du direkt am Element aus, also über event.target.videoWidth und event.target.videoHeight.

Typische Anwendungen: das Seitenverhältnis eines Players anpassen, eine Canvas-Größe für Frame-Verarbeitung nachführen oder die aktuelle Stream-Auflösung anzeigen, etwa in einer Videokonferenz-App.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignistyp, hier immer `"resize"`.
$handler Pflicht	(event: Event) => void		Die Rückruffunktion. Sie bekommt ein einfaches `Event`-Objekt. Die neuen Abmessungen liest du über `event.target.videoWidth` und `event.target.videoHeight` aus.
$options	boolean \| AddEventListenerOptions	false	Optionale Einstellungen wie `once`, `signal` (zum Entfernen per `AbortController`) oder `capture`.

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Das Ereignisobjekt ist ein einfaches Event mit bubbles: false und cancelable: false.

Beispiele

Auflösungswechsel protokollieren (addEventListener)

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

const onResize = (event) => {
  const { videoWidth, videoHeight } = event.target;
  console.log(`Neue Auflösung: ${videoWidth}×${videoHeight}`);
};

video.addEventListener('resize', onResize);
video.src = 'https://example.com/film.mp4';

Neue Auflösung: 1920×1080

Seitenverhältnis des Player-Containers anpassen

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

video.addEventListener('resize', () => {
  const { videoWidth: w, videoHeight: h } = video;
  if (w === 0 || h === 0) return; // Abmessungen noch unbekannt
  container.style.aspectRatio = `${w} / ${h}`;
  console.log(`Seitenverhältnis gesetzt: ${(w / h).toFixed(3)}`);
});

Seitenverhältnis gesetzt: 1.778

Kamera-Stream mit onresize überwachen und Listener wieder entfernen

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

const start = async () => {
  const stream = await navigator.mediaDevices.getUserMedia({ video: true });
  video.srcObject = stream;
  await video.play();

  // on-Property: Canvas an die Stream-Auflösung anpassen
  video.onresize = () => {
    canvas.width = video.videoWidth;
    canvas.height = video.videoHeight;
    console.log(`Canvas: ${canvas.width}×${canvas.height}`);
  };
};

const stop = () => {
  video.onresize = null; // Handler entfernen
  video.srcObject?.getTracks().forEach((t) => t.stop());
};

start();

Canvas: 640×480

Listener per AbortController entfernen

const video = document.querySelector('video');
const controller = new AbortController();

const handleResize = () => {
  console.log('Qualitätswechsel:', video.videoHeight + 'p');
};

video.addEventListener('resize', handleResize, { signal: controller.signal });

// Später, z. B. beim Abbauen der Komponente:
// controller.abort();
// oder klassisch:
// video.removeEventListener('resize', handleResize);

Qualitätswechsel: 720p

// Wichtig · Fallstricke

Nicht verwechseln: Das Ereignis meldet nicht, dass das Element auf der Seite größer oder kleiner wird, etwa durch CSS oder Vollbild. Für die Box-Größe nimmst du ResizeObserver. Das Fenster-Ereignis window.onresize ist ein ganz anderes Ereignis.
Der erste resize kommt normalerweise zusammen mit loadedmetadata. Brauchst du die Abmessungen nur einmal, reicht auch loadedmetadata.
Das Ereignis blubbert nicht. Ereignisdelegation über ein Elternelement klappt deshalb nur mit capture: true.
Bei Audio-Dateien ohne Videospur bleiben videoWidth und videoHeight auf 0, und es kommt kein resize.
Bei gedrehten Videos (Rotation in den Metadaten oder Kamera-Stream im Hochformat) liefern die Browser teils unterschiedliche Werte. Deshalb sollte man immer die aktuellen Werte auslesen, statt Annahmen zu treffen.
Kompatibilität: Chrome, Edge, Firefox und Safari unterstützen das Ereignis, auch für MediaStream-Quellen. Ältere Safari-Versionen haben es bei Auflösungswechseln im Stream nicht immer zuverlässig ausgelöst.

Siehe auch

HTMLVideoElement: enterpictureinpicture HTMLVideoElement: leavepictureinpicture HTMLFormElement: reset HTMLDialogElement: close HTMLMediaElement: ended