OffscreenCanvas.height — Eigenschaft · JavaScript-Referenz

Signatur

OffscreenCanvas.height

Beschreibung

Die Eigenschaft height gibt die Höhe der Bitmap eines OffscreenCanvas in Pixeln zurück. Sie lässt sich auch setzen. Der Startwert kommt aus dem Konstruktor new OffscreenCanvas(width, height). Anders als bei HTMLCanvasElement gibt es kein CSS-Layout: Die Zahl ist immer die echte Auflösung der Zeichenfläche.

Wenn du height setzt, wird der Canvas neu initialisiert. Der Inhalt wird gelöscht und der Zustand des Rendering-Kontexts zurückgesetzt, bei einem 2d-Kontext also Transformationen, fillStyle, Clipping usw. Das passiert auch, wenn du denselben Wert noch einmal zuweist. Bei WebGL-Kontexten wird der Zeichenpuffer neu angelegt, und du musst den Viewport selbst per gl.viewport() anpassen.

Typische Einsätze:

Ein Canvas, der per transferControlToOffscreen() an einen Web Worker übergeben wurde, wird dort an eine neue Größe angepasst.
Ein wiederverwendbarer Hilfs-Canvas wird vor dem Zeichnen oder Skalieren von Bildern auf die richtige Größe gebracht.
Die Auflösung wird an devicePixelRatio angepasst, damit auf HiDPI-Bildschirmen scharf gerendert wird.

Parameter

Name	Typ	Default	Beschreibung
$value	number		Nur beim Setzen: neue Höhe in Pixeln. Der Wert wird in einen `unsigned long` umgewandelt, also eine ganze Zahl ohne Vorzeichen. Nachkommastellen werden abgeschnitten.

Rückgabewert

Typ

number

Beschreibung

Die aktuelle Höhe der Bitmap in Pixeln als nicht negative ganze Zahl.

Beispiele

Höhe auslesen und ändern

const canvas = new OffscreenCanvas(300, 150);
console.log(canvas.height);

canvas.height = 400;
console.log(canvas.height);

// Nachkommastellen werden abgeschnitten
canvas.height = 99.9;
console.log(canvas.height);

150 400 99

Größe ändern löscht Inhalt und Kontextzustand

const canvas = new OffscreenCanvas(100, 100);
const ctx = canvas.getContext('2d');

ctx.fillStyle = 'red';
ctx.fillRect(0, 0, 100, 100);

// Gleicher Wert – trotzdem Reset!
canvas.height = 100;

console.log(ctx.fillStyle);
console.log(ctx.getImageData(50, 50, 1, 1).data[3]);

#000000 0

Größe im Worker an HiDPI anpassen

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

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

// render-worker.js
let canvas, ctx;
self.onmessage = ({ data }) => {
  if (data.canvas) {
    canvas = data.canvas;
    ctx = canvas.getContext('2d');
  }
  if (data.resize && canvas) {
    // Nur bei echter Änderung setzen, sonst unnötiger Reset
    if (canvas.height !== data.resize.height) canvas.height = data.resize.height;
    if (canvas.width !== data.resize.width) canvas.width = data.resize.width;
    ctx.fillStyle = 'steelblue';
    ctx.fillRect(0, 0, canvas.width, canvas.height);
  }
};

Bild mit Hilfs-Canvas skalieren

const scaleToHeight = async (blob, targetHeight) => {
  const bitmap = await createImageBitmap(blob);
  const canvas = new OffscreenCanvas(1, 1);
  canvas.height = targetHeight;
  canvas.width = Math.round(bitmap.width * (targetHeight / bitmap.height));
  canvas.getContext('2d').drawImage(bitmap, 0, 0, canvas.width, canvas.height);
  bitmap.close();
  return canvas.convertToBlob({ type: 'image/webp' });
};

// Wichtig · Fallstricke

Jede Zuweisung setzt den Canvas zurück. Das gilt auch für denselben Wert. Vergleiche vorher mit dem aktuellen Wert, damit du in Render-Schleifen nicht versehentlich alles löschst.
Wurde ein HTMLCanvasElement per transferControlToOffscreen() übergeben, kannst du seine Höhe nur noch über das OffscreenCanvas ändern. Setzt du height am Element selbst, wirft das einen InvalidStateError.
Negative Werte oder NaN werden per unsigned long-Umwandlung zu unerwarteten Zahlen, zum Beispiel NaN → 0. Prüfe die Eingaben deshalb vorher.
Sehr große Werte können die Speichergrenze des Browsers überschreiten. Dann schlägt das Rendern fehl oder der Kontext geht verloren.
Bei WebGL musst du nach der Größenänderung gl.viewport(0, 0, canvas.width, canvas.height) aufrufen.
Browser-Unterstützung: In Chrome/Edge seit Version 69 verfügbar, in Firefox seit 105 und in Safari seit 16.4, dort mit vollem 2D-Kontext erst ab 17. In Workern und im Hauptthread nutzbar.

Siehe auch

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