HTMLVideoElement.width — Eigenschaft · JavaScript-Referenz

Signatur

HTMLVideoElement.width

Beschreibung

Die Eigenschaft width spiegelt das HTML-Attribut width des <video>-Elements wider. Sie legt fest, wie breit der Videobereich in CSS-Pixeln dargestellt wird. Wird die Eigenschaft gesetzt, ändert sich auch das Attribut im DOM und umgekehrt.

Wichtig ist der Unterschied zu videoWidth: width ist die Anzeigebreite des Elements, videoWidth dagegen die tatsächliche Breite des Videostreams in Pixeln (nur lesbar, verfügbar ab dem Ereignis loadedmetadata). Ist kein width-Attribut gesetzt, gibt die Eigenschaft 0 zurück, auch wenn das Video sichtbar gerendert wird. Die tatsächlich gerenderte Größe ergibt sich dann aus der natürlichen Videogröße oder aus CSS.

Typische Einsatzfälle sind das dynamische Anpassen der Playergröße per Skript, das Reservieren von Platz vor dem Laden (gegen Layout-Verschiebungen), oder zusammen mit height das Festlegen eines Seitenverhältnisses. Das Video wird innerhalb der Box standardmäßig mit erhaltenem Seitenverhältnis eingepasst (Letterboxing), außer object-fit sagt etwas anderes.

Parameter

Name	Typ	Default	Beschreibung
$value	number	0	Beim Setzen: nicht-negative ganze Zahl (Breite in CSS-Pixeln). Wird in einen `unsigned long` umgewandelt und als Attribut `width` gespeichert.

Rückgabewert

Typ

number

Beschreibung

Nicht-negative ganze Zahl, nämlich der Wert des width-Attributs in CSS-Pixeln. 0, wenn das Attribut fehlt oder ungültig ist.

Beispiele

Breite auslesen und setzen

// HTML: <video id="player" width="640" src="film.mp4" controls></video>
const video = document.getElementById('player');
console.log(video.width); // 640

video.width = 480;
console.log(video.getAttribute('width')); // "480"

640 "480"

Anzeigebreite und echte Videobreite unterscheiden

const video = document.createElement('video');
video.src = 'film.mp4';
document.body.append(video);

console.log(video.width); // 0, da kein Attribut gesetzt

video.addEventListener('loadedmetadata', () => {
  console.log(`Stream: ${video.videoWidth}x${video.videoHeight}`);
  // Anzeige auf halbe Originalgröße setzen
  video.width = Math.round(video.videoWidth / 2);
  console.log(`Anzeigebreite: ${video.width}`);
});

0 Stream: 1920x1080 Anzeigebreite: 960

Player-Größe per Knopf umschalten

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

const groessen = [320, 640, 960];
let index = 0;

button.addEventListener('click', () => {
  index = (index + 1) % groessen.length;
  video.width = groessen[index];
  button.textContent = `Breite: ${video.width}px`;
});

// Wichtig · Fallstricke

Kein Prozentwert: Die Eigenschaft nimmt nur ganze Pixelwerte an. video.width = '50%' ergibt 0. Für responsive Größen nutzt man CSS (video.style.width = '100%' oder ein Stylesheet).
CSS hat Vorrang: Wenn ein Stylesheet eine width setzt, überschreibt das die Darstellung. Die Eigenschaft liefert trotzdem weiterhin den Attributwert.
Nicht mit videoWidth verwechseln: videoWidth ist nur lesbar und steht erst nach loadedmetadata zur Verfügung. Die tatsächlich gerenderte Breite liefert clientWidth oder getBoundingClientRect().width.
Werden width und height beide gesetzt, können moderne Browser daraus ein aspect-ratio ableiten und Platz reservieren. Das verringert Layout-Verschiebungen (CLS).
Negative Werte werden nach unsigned long umgewandelt und ergeben unerwartete Ergebnisse. Die Eingabe sollte man vorher prüfen.
Kompatibilität: Wird von allen gängigen Browsern seit langem unterstützt.

Siehe auch

HTMLMeterElement.high HTMLVideoElement.height HTMLVideoElement.poster HTMLVideoElement.videoWidth HTMLVideoElement.videoHeight