CanvasRenderingContext2D.imageSmoothingQuality — Eigenschaft · JavaScript-Referenz

Signatur

CanvasRenderingContext2D.imageSmoothingQuality

Beschreibung

Mit imageSmoothingQuality bestimmen Sie, welchen Interpolationsalgorithmus der Browser verwendet, wenn drawImage() ein Bild, Video oder anderes Canvas vergrößert oder verkleinert darstellt. Erlaubt sind die Zeichenketten "low" (Standard), "medium" und "high". Welcher Algorithmus sich konkret hinter der jeweiligen Stufe verbirgt (etwa bilinear, bikubisch oder Lanczos), legt die Spezifikation nicht fest. Das hängt vom Browser ab.

Die Eigenschaft wirkt nur, wenn imageSmoothingEnabled den Wert true hat, was der Standard ist. Ist die Glättung abgeschaltet, werden die Pixel nach dem Nächster-Nachbar-Verfahren kopiert, und imageSmoothingQuality hat keine Wirkung.

Einsetzen sollten Sie "high" vor allem beim Verkleinern von Fotos, zum Beispiel für Vorschaubilder (Thumbnails) oder um Bilder vor dem Hochladen zu verkleinern. Dort vermeidet die höhere Stufe Treppenstufen und Moiré-Muster. "low" ist schneller und reicht für Animationen oder Spiele mit vielen Zeichenvorgängen pro Bild.

Die Eigenschaft gehört zum Zeichenzustand. Sie wird also mit save() gesichert und mit restore() wiederhergestellt. Außerdem gibt es sie auch bei OffscreenCanvasRenderingContext2D.

Parameter

Name	Typ	Default	Beschreibung
$value	"low" \| "medium" \| "high"	"low"	Die gewünschte Glättungsqualität beim Zuweisen. Ungültige Werte werden ohne Fehlermeldung ignoriert, der bisherige Wert bleibt dann erhalten.

Rückgabewert

Typ

"low" | "medium" | "high"

Beschreibung

Die aktuell eingestellte Qualitätsstufe als Zeichenkette.

Beispiele

Qualitätsstufe lesen und setzen

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

console.log(ctx.imageSmoothingQuality); // Standardwert

ctx.imageSmoothingQuality = 'high';
console.log(ctx.imageSmoothingQuality);

// Ungültige Werte werden ignoriert
ctx.imageSmoothingQuality = 'ultra';
console.log(ctx.imageSmoothingQuality);

low high high

Hochwertiges Vorschaubild aus einer hochgeladenen Datei erzeugen

const createThumbnail = async (file, maxSize = 200) => {
  const bitmap = await createImageBitmap(file);
  const scale = Math.min(maxSize / bitmap.width, maxSize / bitmap.height, 1);

  const canvas = document.createElement('canvas');
  canvas.width = Math.round(bitmap.width * scale);
  canvas.height = Math.round(bitmap.height * scale);

  const ctx = canvas.getContext('2d');
  ctx.imageSmoothingEnabled = true;
  ctx.imageSmoothingQuality = 'high'; // bestmögliche Glättung beim Verkleinern
  ctx.drawImage(bitmap, 0, 0, canvas.width, canvas.height);
  bitmap.close();

  return new Promise((resolve) => canvas.toBlob(resolve, 'image/jpeg', 0.85));
};

document.querySelector('#upload').addEventListener('change', async (e) => {
  const blob = await createThumbnail(e.target.files[0]);
  console.log(`Vorschaubild: ${blob.size} Bytes`);
});

Vorschaubild: 14823 Bytes

Qualitätsstufen nebeneinander vergleichen

const img = new Image();
img.src = 'foto.jpg';
await img.decode();

const canvas = document.querySelector('#vergleich');
const ctx = canvas.getContext('2d');
const w = 150;
const h = Math.round(img.height * (w / img.width));

['low', 'medium', 'high'].forEach((quality, i) => {
  ctx.save();
  ctx.imageSmoothingQuality = quality;
  ctx.drawImage(img, i * (w + 10), 0, w, h);
  ctx.restore(); // Qualität gehört zum Zeichenzustand
  ctx.fillText(quality, i * (w + 10), h + 14);
});

Pixel-Art: Glättung ganz abschalten

const ctx = document.querySelector('#spiel').getContext('2d');
const sprite = new Image();
sprite.src = 'held-16x16.png';
sprite.onload = () => {
  // imageSmoothingQuality wirkt hier nicht, weil die Glättung aus ist
  ctx.imageSmoothingEnabled = false;
  ctx.drawImage(sprite, 0, 0, 128, 128); // scharfe, 8-fach vergrößerte Pixel
};

// Wichtig · Fallstricke

Nur zusammen mit Glättung wirksam: Wenn imageSmoothingEnabled = false gesetzt ist, wird imageSmoothingQuality ignoriert.
Das Ergebnis hängt vom Browser ab: Die Spezifikation schreibt keine Algorithmen vor. Die Stufe "high" kann daher in Chrome, Safari und Firefox unterschiedlich aussehen. Manche Browser unterscheiden intern auch nicht zwischen allen drei Stufen.
Größenänderung setzt den Wert zurück: Wenn Sie canvas.width oder canvas.height setzen, wird der gesamte Kontextzustand zurückgesetzt, auch diese Eigenschaft (zurück auf "low"). Setzen Sie die Größe deshalb vor der Qualitätsstufe.
Keine Fehlermeldung: Tippfehler wie "High" werden stillschweigend ignoriert. Groß- und Kleinschreibung spielen eine Rolle.
Leistung: "high" kann spürbar langsamer sein. Bei Animationen mit vielen drawImage()-Aufrufen pro Bild lohnt es sich, das zu messen.
Starkes Verkleinern: Wird ein Bild auf weniger als etwa die Hälfte verkleinert, liefert schrittweises Verkleinern (jeweils halbieren) oft trotzdem bessere Ergebnisse.
Kompatibilität: Chromium und Safari unterstützen die Eigenschaft seit Langem, Firefox erst ab Version 128 (2024). In älteren Firefox-Versionen ist sie undefined, und das Zuweisen hat keine Wirkung.

Siehe auch

CanvasRenderingContext2D.imageSmoothingEnabled CanvasRenderingContext2D.drawImage() CanvasRenderingContext2D OffscreenCanvasRenderingContext2D HTMLCanvasElement.toBlob()