HTMLCanvasElement.toDataURL() — Methode · JavaScript-Referenz

Signatur

HTMLCanvasElement.prototype.toDataURL(type, quality)

Beschreibung

toDataURL() erzeugt aus dem aktuellen Pixelinhalt eines Canvas eine Zeichenkette der Form data:image/png;base64,…. Diese Daten-URL lässt sich direkt als src eines <img>, als href eines Download-Links oder als Textwert in JSON bzw. einem Formularfeld verwenden.

Typische Einsatzfälle sind Bildvorschauen nach clientseitigem Zuschneiden oder Verkleinern, das Exportieren von Zeichnungen und Diagrammen, Screenshots von WebGL-Szenen oder das Speichern kleiner Grafiken im localStorage.

Die Methode arbeitet synchron und blockiert den Haupt-Thread, bis das Bild kodiert ist. Durch die Base64-Kodierung ist das Ergebnis etwa 33 % größer als die Binärdaten. Bei großen Canvas-Flächen oder zum Hochladen ist deshalb meist canvas.toBlob() die bessere Wahl, weil es asynchron arbeitet und einen Blob liefert.

Unterstützt der Browser das angeforderte Format nicht, fällt er stillschweigend auf image/png zurück. Hat das Canvas eine Breite oder Höhe von 0, wird "data:," zurückgegeben.

Parameter

Name	Typ	Default	Beschreibung
$type	string	"image/png"	MIME-Typ des Bildformats, z. B. `"image/png"`, `"image/jpeg"` oder `"image/webp"`. Nicht unterstützte Typen führen zu PNG.
$quality	number	browserabhängig (meist 0.92)	Qualität zwischen `0` und `1` für verlustbehaftete Formate (`image/jpeg`, `image/webp`). Bei PNG oder ungültigen Werten wird der Standardwert verwendet.

Rückgabewert

Typ

string

Beschreibung

Eine Daten-URL (data:<MIME-Typ>;base64,<Daten>) mit dem kodierten Bild bzw. "data:," bei einem Canvas ohne Fläche.

Beispiele

Canvas-Zeichnung als Bild anzeigen

const canvas = document.createElement('canvas');
canvas.width = 200;
canvas.height = 100;
const ctx = canvas.getContext('2d');
ctx.fillStyle = '#0a7';
ctx.fillRect(0, 0, 200, 100);
ctx.fillStyle = '#fff';
ctx.font = '24px sans-serif';
ctx.fillText('Hallo!', 60, 58);

const url = canvas.toDataURL();
console.log(url.slice(0, 22));

const img = new Image();
img.src = url;
document.body.append(img);

data:image/png;base64,

Zeichnung als JPEG herunterladen

const downloadCanvas = (canvas, dateiname = 'zeichnung.jpg') => {
  const link = document.createElement('a');
  link.href = canvas.toDataURL('image/jpeg', 0.85);
  link.download = dateiname;
  link.click();
};

downloadCanvas(document.querySelector('#zeichenflaeche'));

Hochgeladenes Bild verkleinern (Vorschau/Thumbnail)

const input = document.querySelector('input[type=file]');

input.addEventListener('change', async () => {
  const datei = input.files[0];
  if (!datei) return;

  const bitmap = await createImageBitmap(datei);
  const maxBreite = 300;
  const faktor = Math.min(1, maxBreite / bitmap.width);

  const canvas = document.createElement('canvas');
  canvas.width = Math.round(bitmap.width * faktor);
  canvas.height = Math.round(bitmap.height * faktor);
  canvas.getContext('2d').drawImage(bitmap, 0, 0, canvas.width, canvas.height);

  const thumbnail = canvas.toDataURL('image/webp', 0.8);
  document.querySelector('#vorschau').src = thumbnail;
  console.log(`Größe: ${Math.round(thumbnail.length / 1024)} KB`);
});

Größe: 18 KB

Format-Unterstützung prüfen

const unterstuetztFormat = (mime) => {
  const c = document.createElement('canvas');
  c.width = c.height = 1;
  return c.toDataURL(mime).startsWith(`data:${mime}`);
};

console.log(unterstuetztFormat('image/webp'));
console.log(unterstuetztFormat('image/avif'));

true false

// Wichtig · Fallstricke

Tainted Canvas / CORS: Wurde ein Bild von einer fremden Herkunft ohne CORS-Freigabe auf das Canvas gezeichnet, ist das Canvas „verunreinigt“. toDataURL() wirft dann einen SecurityError. Abhilfe: img.crossOrigin = 'anonymous' setzen bevor src zugewiesen wird, und der Server muss Access-Control-Allow-Origin senden.
Performance: Die Methode ist synchron und kann bei großen Canvas-Flächen (z. B. 4K) den Haupt-Thread spürbar blockieren. Für Uploads toBlob() oder OffscreenCanvas.convertToBlob() bevorzugen.
Größe: Base64 vergrößert die Daten um ca. 33 %; localStorage ist meist auf ca. 5 MB begrenzt.
Transparenz: JPEG kennt keinen Alphakanal – transparente Bereiche werden schwarz. Vorher ggf. einen weißen Hintergrund zeichnen.
Formate: PNG ist überall garantiert, WebP-Export fehlt in Safari vor Version 17; nicht unterstützte Formate liefern still PNG zurück.
WebGL: Ohne preserveDrawingBuffer: true kann das Ergebnis leer sein, wenn außerhalb des Render-Frames aufgerufen wird.
Datenschutz: Die Methode wird häufig für Canvas-Fingerprinting missbraucht; einige Browser (z. B. Firefox mit resistFingerprinting, Brave) liefern verrauschte oder leere Daten.

Siehe auch

HTMLAreaElement.toString() HTMLCanvasElement.toBlob() HTMLCanvasElement.getContext() HTMLCanvasElement.captureStream() HTMLCanvasElement.transferControlToOffscreen()