ImageBitmap.width — Eigenschaft · JavaScript-Referenz

Signatur

ImageBitmap.width

Beschreibung

ImageBitmap.width gibt die tatsächliche (intrinsische) Breite der Bilddaten zurück, die in einem ImageBitmap gespeichert sind. Der Wert ist ein vorzeichenloser Ganzzahlwert (unsigned long) und lässt sich nicht verändern. Zusammen mit ImageBitmap.height beschreibt er die Abmessungen der Bitmap.

Welcher Wert herauskommt, hängt davon ab, wie das ImageBitmap mit createImageBitmap() erzeugt wurde: Wird ein Ausschnitt (sx, sy, sw, sh) angegeben, entspricht width der Ausschnittbreite. Mit der Option resizeWidth (bzw. nur resizeHeight bei proportionaler Skalierung) wird die Bitmap bereits bei der Erzeugung skaliert, und width spiegelt die neue Breite wider.

Typische Einsatzfälle sind das Dimensionieren eines <canvas> oder OffscreenCanvas passend zum Bild, das Berechnen von Seitenverhältnissen, das Zentrieren beim Zeichnen mit drawImage() sowie das Anlegen von WebGL-Texturen mit der richtigen Größe.

Nach einem Aufruf von ImageBitmap.close() sind die Bilddaten freigegeben; width liefert dann 0.

Rückgabewert

Typ

number

Beschreibung

Breite der Bitmap in CSS-Pixeln als nicht-negative Ganzzahl; 0, wenn das ImageBitmap mit close() freigegeben wurde.

Beispiele

Canvas an die Bildgröße anpassen

const response = await fetch('/bilder/landschaft.jpg');
const blob = await response.blob();
const bitmap = await createImageBitmap(blob);

const canvas = document.querySelector('canvas');
canvas.width = bitmap.width;   // Canvas exakt so breit wie das Bild
canvas.height = bitmap.height;

canvas.getContext('2d').drawImage(bitmap, 0, 0);
console.log(`Bild: ${bitmap.width} × ${bitmap.height}`);

Bild: 1920 × 1080

Ausschnitt und Skalierung beeinflussen width

const img = document.querySelector('#foto'); // z. B. 1200 × 800
await img.decode();

// Ausschnitt von 400 × 300 Pixeln
const ausschnitt = await createImageBitmap(img, 100, 50, 400, 300);
console.log(ausschnitt.width); // 400

// Proportional auf 300 px Breite verkleinert (Thumbnail)
const thumb = await createImageBitmap(img, {
  resizeWidth: 300,
  resizeQuality: 'high'
});
console.log(thumb.width, thumb.height);

400 300 200

Seitenverhältnis im Web Worker berechnen und Speicher freigeben

// worker.js
self.onmessage = async ({ data: blob }) => {
  const bitmap = await createImageBitmap(blob);
  const ratio = bitmap.width / bitmap.height;
  const format = ratio > 1 ? 'Querformat' : ratio < 1 ? 'Hochformat' : 'Quadrat';

  self.postMessage({ width: bitmap.width, ratio: ratio.toFixed(2), format });

  bitmap.close();
  console.log(bitmap.width); // nach close() immer 0
};

// Wichtig · Fallstricke

Schreibgeschützt: Eine Zuweisung wie bitmap.width = 100 wird ignoriert (im Strict Mode TypeError). Zum Skalieren beim Erzeugen die Optionen resizeWidth/resizeHeight von createImageBitmap() oder beim Zeichnen die Zielgröße von drawImage() verwenden.
Nach close() ist der Wert 0: Auch ein per postMessage() übertragenes (transferiertes) ImageBitmap ist im Absender danach leer und meldet width === 0. Wer die Größe noch braucht, sollte sie vorher zwischenspeichern.
Keine Anpassung an devicePixelRatio: Der Wert beschreibt die Pixel der Bitmap-Daten, nicht die Darstellungsgröße auf dem Bildschirm. Für scharfe Darstellung auf HiDPI-Displays muss die Canvas-Größe separat berechnet werden.
EXIF-Ausrichtung: Je nach Option imageOrientation ('from-image' als Standard in aktuellen Browsern, 'flipY', früher 'none') können bei gedrehten JPEG-Fotos Breite und Höhe vertauscht erscheinen.
Kompatibilität: In allen modernen Browsern verfügbar, auch in Workern. Safari unterstützt ImageBitmap vollständig erst ab Version 15; die resize*-Optionen werden in älteren Firefox-Versionen nicht unterstützt.

Siehe auch

ImageBitmap ImageBitmap.height ImageBitmap.close() CanvasRenderingContext2D.drawImage() OffscreenCanvas ImageCapture.track