OffscreenCanvas.convertToBlob() — Methode · JavaScript-Referenz

Signatur

OffscreenCanvas.prototype.convertToBlob(options)

Beschreibung

convertToBlob() wandelt das Bild eines OffscreenCanvas in eine kodierte Bilddatei um, standardmäßig PNG, optional JPEG oder WebP. Die Methode ist das Gegenstück zu HTMLCanvasElement.toBlob(). Statt eines Callbacks gibt sie jedoch ein Promise<Blob> zurück und lässt sich deshalb direkt mit await verwenden.

Praktisch ist die Methode vor allem in Web Workern: Dort gibt es kein DOM, man kann aber ein OffscreenCanvas anlegen, Bilder skalieren, mit Wasserzeichen versehen oder Vorschaubilder erzeugen und das Ergebnis als Blob an den Hauptthread zurückschicken, hochladen oder in IndexedDB speichern. Weil das Kodieren im Hintergrund läuft, blockiert es die Benutzeroberfläche nicht.

Der entstandene Blob lässt sich mit URL.createObjectURL() anzeigen, per fetch() oder FormData hochladen oder mit blob.arrayBuffer() weiterverarbeiten. Ob das Bild verlustbehaftet komprimiert wird, legt man über options.type und options.quality fest.

Parameter

Name	Typ	Default	Beschreibung
$options	Object	{}	Optionales Objekt mit Einstellungen für das Kodieren.
$options.type	string	"image/png"	MIME-Typ des Zielformats, z. B. `"image/png"`, `"image/jpeg"` oder `"image/webp"`. Kennt der Browser das Format nicht, wird PNG erzeugt.
$options.quality	number	vom Browser abhängig (meist ca. 0.92 für JPEG)	Zahl zwischen `0` und `1` für die Qualität verlustbehafteter Formate (`image/jpeg`, `image/webp`). Bei PNG hat sie keine Wirkung.

Rückgabewert

Typ

Promise<Blob>

Beschreibung

Ein Promise, das mit einem Blob erfüllt wird, der das kodierte Bild enthält. blob.type gibt das tatsächlich verwendete Format an.

Beispiele

Einfaches PNG aus einem OffscreenCanvas

const canvas = new OffscreenCanvas(200, 100);
const ctx = canvas.getContext('2d');
ctx.fillStyle = '#0a84ff';
ctx.fillRect(0, 0, 200, 100);
ctx.fillStyle = '#fff';
ctx.font = '24px sans-serif';
ctx.fillText('Hallo', 60, 58);

const blob = await canvas.convertToBlob();
console.log(blob.type, blob.size > 0);

// Im Hauptthread anzeigen
const img = document.createElement('img');
img.src = URL.createObjectURL(blob);
document.body.append(img);

image/png true

Vorschaubild im Web Worker erzeugen (JPEG)

// worker.js
self.onmessage = async ({ data: file }) => {
  const bitmap = await createImageBitmap(file);
  const scale = Math.min(1, 320 / bitmap.width);
  const w = Math.round(bitmap.width * scale);
  const h = Math.round(bitmap.height * scale);

  const canvas = new OffscreenCanvas(w, h);
  canvas.getContext('2d').drawImage(bitmap, 0, 0, w, h);
  bitmap.close();

  const thumb = await canvas.convertToBlob({ type: 'image/jpeg', quality: 0.8 });
  self.postMessage(thumb);
};

// main.js
const worker = new Worker('worker.js');
worker.onmessage = ({ data: thumb }) => {
  console.log('Thumbnail:', thumb.type, thumb.size, 'Bytes');
};
document.querySelector('input[type=file]').addEventListener('change', (e) => {
  worker.postMessage(e.target.files[0]);
});

Thumbnail: image/jpeg 14532 Bytes

WebP mit Rückfall prüfen und hochladen

const exportAndUpload = async (canvas) => {
  let blob = await canvas.convertToBlob({ type: 'image/webp', quality: 0.85 });
  if (blob.type !== 'image/webp') {
    // Browser kann kein WebP kodieren → PNG wurde erzeugt
    console.warn('WebP nicht unterstützt, verwende', blob.type);
  }
  const form = new FormData();
  form.append('bild', blob, `export.${blob.type.split('/')[1]}`);
  const res = await fetch('/upload', { method: 'POST', body: form });
  return res.ok;
};

const canvas = new OffscreenCanvas(64, 64);
canvas.getContext('2d').fillRect(0, 0, 64, 64);
console.log(await exportAndUpload(canvas));

true

// Wichtig · Fallstricke

Fehler: Das Promise wird mit einem DOMException abgelehnt, wenn die Canvas-Breite oder -Höhe 0 ist (IndexSizeError), wenn das Canvas an einen placeholder-Kontext übertragen bzw. abgelöst wurde (InvalidStateError) oder wenn es durch Bilder fremder Herkunft ohne CORS „verunreinigt“ ist (SecurityError).
Format prüfen: Kennt der Browser den gewünschten MIME-Typ nicht, erhält man ohne Fehlermeldung ein PNG. Prüfen Sie deshalb blob.type. Safari konnte lange kein WebP kodieren.
Bei image/jpeg werden transparente Bereiche meist schwarz dargestellt. Füllen Sie vorher einen Hintergrund, wenn Sie Weiß brauchen.
Nicht verwechseln mit HTMLCanvasElement.toBlob(callback, type, quality): Diese Methode erwartet einen Callback und einzelne Argumente statt eines Optionsobjekts.
Mit URL.createObjectURL() erzeugte URLs sollten Sie mit URL.revokeObjectURL() wieder freigeben, sonst bleibt Speicher belegt.
Kompatibilität: In Chrome/Edge ab Version 69, in Firefox ab 105 (davor nur hinter einem Flag), in Safari ab 16.4. Funktioniert im Hauptthread und in Workern.

Siehe auch

OffscreenCanvas OffscreenCanvas.transferToImageBitmap() HTMLCanvasElement.toBlob() HTMLCanvasElement.transferControlToOffscreen() Blob URL.createObjectURL()