OffscreenCanvas.width — Eigenschaft · JavaScript-Referenz

Signatur

OffscreenCanvas.width

Beschreibung

Die Eigenschaft width gibt die Breite der Zeichenfläche eines OffscreenCanvas-Objekts in CSS-unabhängigen Bitmap-Pixeln zurück und erlaubt auch, sie zu ändern. Der Anfangswert entspricht dem ersten Argument des Konstruktors new OffscreenCanvas(width, height).

Da ein OffscreenCanvas nicht im DOM hängt, gibt es keine CSS-Größe. width und height legen also allein die Auflösung des internen Bitmaps fest. Das ist vor allem in Web Workers nützlich, wo man per HTMLCanvasElement.transferControlToOffscreen() die Kontrolle über ein sichtbares Canvas erhält und etwa bei Größenänderungen des Fensters die Auflösung nachführen muss.

Wichtig: Wird width gesetzt – auch auf denselben Wert –, wird das Bitmap zurückgesetzt: Der gesamte Inhalt wird gelöscht und der Zustand des 2D-Kontexts (Transformationen, fillStyle, Clipping usw.) auf die Standardwerte zurückgesetzt. Nach einer Größenänderung muss daher neu gezeichnet werden.

Parameter

Name	Typ	Default	Beschreibung
$wert	number		Beim Setzen: neue Breite in Pixeln. Der Wert wird in eine vorzeichenlose 64-Bit-Ganzzahl (`unsigned long long`) umgewandelt, Nachkommastellen werden abgeschnitten.

Rückgabewert

Typ

number

Beschreibung

Die aktuelle Breite des Bitmaps in Pixeln als nicht negative Ganzzahl.

Beispiele

Breite lesen und ändern

const offscreen = new OffscreenCanvas(256, 256);
console.log(offscreen.width);

offscreen.width = 512;
console.log(offscreen.width);

// Nachkommastellen werden abgeschnitten
offscreen.width = 300.9;
console.log(offscreen.width);

256 512 300

Inhalt geht beim Setzen der Breite verloren

const offscreen = new OffscreenCanvas(100, 100);
const ctx = offscreen.getContext('2d');
ctx.fillStyle = 'red';
ctx.fillRect(0, 0, 100, 100);

// Gleicher Wert – trotzdem Reset!
offscreen.width = 100;

const pixel = ctx.getImageData(10, 10, 1, 1).data;
console.log(Array.from(pixel));
console.log(ctx.fillStyle);

[0, 0, 0, 0] #000000

Resize im Worker nach transferControlToOffscreen()

// main.js
const canvas = document.querySelector('canvas');
const offscreen = canvas.transferControlToOffscreen();
const worker = new Worker('render-worker.js');
worker.postMessage({ type: 'init', canvas: offscreen }, [offscreen]);

new ResizeObserver(([entry]) => {
  const dpr = window.devicePixelRatio;
  worker.postMessage({
    type: 'resize',
    width: Math.round(entry.contentRect.width * dpr),
    height: Math.round(entry.contentRect.height * dpr)
  });
}).observe(canvas);

// render-worker.js
let canvas, ctx;
self.onmessage = ({ data }) => {
  if (data.type === 'init') {
    canvas = data.canvas;
    ctx = canvas.getContext('2d');
  } else if (data.type === 'resize') {
    canvas.width = data.width;
    canvas.height = data.height;
    draw(); // nach dem Reset neu zeichnen
  }
};

const draw = () => {
  ctx.fillStyle = 'steelblue';
  ctx.fillRect(0, 0, canvas.width, canvas.height);
};

// Wichtig · Fallstricke

Reset beim Setzen: Jede Zuweisung an width löscht den Inhalt und setzt den Kontextzustand zurück – auch wenn sich der Wert nicht ändert. Vorher prüfen: if (canvas.width !== w) canvas.width = w;
Nach transferControlToOffscreen() kann width des ursprünglichen HTMLCanvasElement nicht mehr gesetzt werden (InvalidStateError); Größenänderungen müssen über das OffscreenCanvas erfolgen.
Wurde das OffscreenCanvas per postMessage an einen anderen Kontext übertragen (detached), wirft das Setzen einen InvalidStateError.
Für scharfe Darstellung auf HiDPI-Displays die Breite mit devicePixelRatio multiplizieren – im Worker ist dieser Wert nicht verfügbar und muss vom Hauptthread übermittelt werden.
Sehr große Werte können Speicher- bzw. Implementierungsgrenzen überschreiten; getContext() oder Zeichenoperationen schlagen dann fehl.
Kompatibilität: Chrome/Edge 69+, Firefox 105+, Safari 16.4+ (2D-Kontext in Safari erst ab 16.4, WebGL ab 17).

Siehe auch

OffscreenCanvas.height OffscreenCanvas OffscreenCanvas.prototype.getContext() HTMLCanvasElement.prototype.transferControlToOffscreen() HTMLCanvasElement.width MediaTrackConstraints.width MediaTrackSettings.width