HTMLCanvasElement.width — Eigenschaft · JavaScript-Referenz

Signatur

HTMLCanvasElement.width

Beschreibung

Die Eigenschaft width legt fest, wie viele Pixel die interne Zeichenfläche (der sogenannte Bitmap-Puffer) eines <canvas>-Elements breit ist. Sie spiegelt das HTML-Attribut width wider. Fehlt das Attribut oder ist sein Wert ungültig, gilt der Standardwert 300. Zusammen mit height (Standard: 150) bestimmt sie die Auflösung, in der gezeichnet wird.

Wichtig ist der Unterschied zwischen der Zeichenflächen-Größe (canvas.width) und der Anzeigegröße (CSS-Eigenschaft width). Ohne CSS-Angabe wird das Canvas genau in seiner Zeichenflächen-Größe angezeigt, je Pixel ein CSS-Pixel. Mit CSS lässt sich das Element dagegen strecken oder stauchen. Dann wird der Inhalt skaliert und wirkt unscharf oder verzerrt.

Wenn du width setzt, wird die Zeichenfläche vollständig zurückgesetzt. Alle Pixel werden transparent, und der Zustand des Kontexts (Transformationen, fillStyle, lineWidth, Clipping-Bereiche, der Stack von save()) geht verloren. Das passiert sogar, wenn du denselben Wert erneut zuweist. Für scharfe Grafiken auf Bildschirmen mit hoher Pixeldichte setzt man width meist auf die CSS-Breite multipliziert mit window.devicePixelRatio und skaliert den Kontext entsprechend.

Parameter

Name	Typ	Default	Beschreibung
$value	number	300	Beim Setzen: nicht-negative ganze Zahl für die Breite der Zeichenfläche in Pixeln. Nachkommastellen werden abgeschnitten, ungültige oder negative Werte führen zum Standardwert `300`.

Rückgabewert

Typ

number

Beschreibung

Die aktuelle Breite der Zeichenfläche in Pixeln als nicht-negative ganze Zahl (unsigned long).

Beispiele

Standardgröße auslesen und ändern

const canvas = document.createElement('canvas');
console.log(canvas.width, canvas.height); // Standardwerte

canvas.width = 640;
canvas.height = 480;
console.log(canvas.width, canvas.getAttribute('width'));

300 150 640 "640"

Scharfe Darstellung auf HiDPI-Bildschirmen

const canvas = document.querySelector('#chart');
const ctx = canvas.getContext('2d');

const setupCanvas = () => {
  const dpr = window.devicePixelRatio || 1;
  const { width, height } = canvas.getBoundingClientRect();

  // Zeichenfläche in Gerätepixeln, Anzeige bleibt in CSS-Pixeln
  canvas.width = Math.round(width * dpr);
  canvas.height = Math.round(height * dpr);

  // Das Zurücksetzen der Größe löscht die Transformation, also neu skalieren
  ctx.scale(dpr, dpr);

  ctx.fillStyle = '#0a7';
  ctx.fillRect(10, 10, width - 20, 40);
};

setupCanvas();

Canvas an Containergröße anpassen mit ResizeObserver

const canvas = document.querySelector('canvas');
const ctx = canvas.getContext('2d');

const draw = () => {
  ctx.strokeStyle = 'crimson';
  ctx.lineWidth = 4;
  ctx.strokeRect(0, 0, canvas.width, canvas.height);
};

const observer = new ResizeObserver(([entry]) => {
  const { inlineSize, blockSize } = entry.contentBoxSize[0];
  const newWidth = Math.round(inlineSize);
  // Nur bei echter Änderung setzen, denn jede Zuweisung löscht den Inhalt
  if (canvas.width !== newWidth) {
    canvas.width = newWidth;
    canvas.height = Math.round(blockSize);
    draw(); // Inhalt und Kontext-Stile neu anwenden
  }
});

observer.observe(canvas);

Zuweisung setzt den Inhalt zurück

const canvas = document.createElement('canvas');
const ctx = canvas.getContext('2d');
ctx.fillStyle = 'red';
ctx.fillRect(0, 0, 10, 10);

console.log(ctx.getImageData(5, 5, 1, 1).data[0]); // Rotanteil

canvas.width = canvas.width; // gleiche Breite, trotzdem Reset
console.log(ctx.getImageData(5, 5, 1, 1).data[0]);
console.log(ctx.fillStyle);

255 0 #000000

// Wichtig · Fallstricke

Zuweisen löscht alles: Jede Zuweisung an width, auch mit dem gleichen Wert, leert die Zeichenfläche und setzt den Kontext-Zustand zurück. Deshalb nur bei echter Größenänderung setzen und danach neu zeichnen. Um nur den Inhalt zu löschen, nimm ctx.clearRect() oder ctx.reset().
Nicht mit CSS verwechseln: canvas.style.width verändert nur die Anzeigegröße, nicht die Auflösung. Weicht das Seitenverhältnis von width/height ab, wird der Inhalt verzerrt.
Performance und Speicher: Sehr große Werte (etwa bei hohem devicePixelRatio) brauchen viel Speicher. Browser haben Obergrenzen für Fläche und Kantenlänge (je nach Browser und Gerät oft um 16 384 bis 32 767 px). Wird sie überschritten, zeichnet der Canvas nichts mehr, ohne dass eine Fehlermeldung erscheint.
OffscreenCanvas: Nach transferControlToOffscreen() löst das Setzen von width am Element einen InvalidStateError aus. Die Größe wird dann über OffscreenCanvas.width gesteuert.
Die Eigenschaft wird von allen Browsern unterstützt.

Siehe auch

HTMLCanvasElement.height HTMLCanvasElement.getContext() HTMLCanvasElement Window.devicePixelRatio OffscreenCanvas ResizeObserver HTMLCanvasElement.mozOpaque