CanvasRenderingContext2D.filter — Eigenschaft · JavaScript-Referenz

Signatur

CanvasRenderingContext2D.filter

Beschreibung

Die Eigenschaft filter des CanvasRenderingContext2D nimmt einen String in der Syntax der CSS-Eigenschaft filter entgegen. Damit lassen sich Formen, Texte und Bilder beim Zeichnen weichzeichnen, entsättigen, aufhellen, einfärben oder mit einem Schlagschatten versehen, ohne die Pixel mühsam per getImageData() selbst zu bearbeiten.

Der Filter wirkt nur auf Zeichenoperationen, die nach dem Setzen folgen (z. B. fillRect(), fillText(), drawImage()). Bereits gezeichnete Inhalte bleiben unverändert. Wer ein vorhandenes Canvas nachträglich filtern möchte, zeichnet es mit gesetztem Filter per drawImage() auf sich selbst oder auf ein zweites Canvas.

Unterstützte Werte:

"none" – kein Filter (Standardwert)
CSS-Filterfunktionen: blur(), brightness(), contrast(), drop-shadow(), grayscale(), hue-rotate(), invert(), opacity(), saturate(), sepia()
url() – Verweis auf ein SVG-<filter>-Element im Dokument, z. B. "url(#meinFilter)"

Mehrere Funktionen können durch Leerzeichen getrennt kombiniert werden; sie werden von links nach rechts angewendet. Die Eigenschaft gehört zum Zeichenzustand und wird daher von save() und restore() gesichert bzw. wiederhergestellt.

Parameter

Name	Typ	Default	Beschreibung
$value	string	"none"	Filterliste in CSS-Syntax, z. B. `"blur(4px) grayscale(100%)"`, oder `"none"`. Ungültige Werte werden stillschweigend ignoriert.

Rückgabewert

Typ

string

Beschreibung

Der aktuell gesetzte Filter-String bzw. "none", wenn kein Filter aktiv ist.

Beispiele

Foto in Graustufen zeichnen

const canvas = document.querySelector('#bild');
const ctx = canvas.getContext('2d');

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

canvas.width = img.naturalWidth;
canvas.height = img.naturalHeight;

// Filter gilt für alle folgenden Zeichenaufrufe
ctx.filter = 'grayscale(100%) contrast(120%)';
ctx.drawImage(img, 0, 0);

console.log(ctx.filter);

grayscale(100%) contrast(120%)

Filter mit save()/restore() begrenzen

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

ctx.save();
ctx.filter = 'blur(6px) drop-shadow(4px 4px 4px rgba(0, 0, 0, 0.5))';
ctx.fillStyle = 'tomato';
ctx.fillRect(20, 20, 120, 80); // weichgezeichnet mit Schatten
ctx.restore();

// Filter ist wieder zurückgesetzt
ctx.fillStyle = 'steelblue';
ctx.fillRect(160, 20, 120, 80); // scharf

console.log(ctx.filter);

none

Vorhandenes Canvas nachträglich filtern (Vorschau-Effekt)

const quelle = document.querySelector('#editor');
const vorschau = document.querySelector('#vorschau');
const vctx = vorschau.getContext('2d');

const applyFilter = (filterString) => {
  vorschau.width = quelle.width;
  vorschau.height = quelle.height;
  vctx.filter = filterString;
  // Inhalt des Editors mit Filter ins Vorschau-Canvas kopieren
  vctx.drawImage(quelle, 0, 0);
};

document.querySelector('#sepia').addEventListener('click', () => {
  applyFilter('sepia(80%) brightness(110%)');
});

SVG-Filter per url() verwenden

// Im HTML: <svg width="0" height="0"><filter id="rotKanal"><feColorMatrix type="matrix" values="1 0 0 0 0  0 0 0 0 0  0 0 0 0 0  0 0 0 1 0"/></filter></svg>
const ctx = document.querySelector('canvas').getContext('2d');

ctx.filter = 'url(#rotKanal)';
ctx.fillStyle = 'purple';
ctx.fillRect(10, 10, 100, 100); // nur der Rotanteil bleibt sichtbar

// Wichtig · Fallstricke

Nicht rückwirkend: Der Filter beeinflusst nur später gezeichnete Inhalte. Wer nach dem Setzen nichts mehr zeichnet, sieht keinen Effekt.
Ungültige Werte (z. B. "blur(5)" ohne Einheit) werden ohne Fehlermeldung ignoriert; der vorherige Wert bleibt bestehen. Zum Prüfen ctx.filter nach dem Setzen zurücklesen.
Zustand: Den Filter nach Gebrauch mit ctx.filter = 'none' oder über save()/restore() zurücksetzen – sonst wirkt er auf alle weiteren Zeichnungen.
Leistung: Vor allem blur() und drop-shadow() mit großen Radien sind teuer. In Animationsschleifen (requestAnimationFrame) sparsam einsetzen oder gefilterte Ergebnisse in einem Offscreen-Canvas zwischenspeichern.
Browser-Kompatibilität: Chrome/Edge und Firefox unterstützen die Eigenschaft seit Jahren, Safari erst ab Version 18 (2024). In älteren Safari-Versionen wird der Wert ignoriert – ggf. per Feature-Test ('filter' in ctx) prüfen und auf eigene Pixelbearbeitung mit getImageData() ausweichen. Auch in OffscreenCanvasRenderingContext2D verfügbar; url()-Filter funktionieren dort mangels DOM jedoch nicht.
Sicherheit: Werden Bilder aus fremden Ursprüngen ohne CORS gezeichnet, ist das Canvas „tainted“ – daran ändert ein Filter nichts; getImageData() und toDataURL() schlagen weiterhin fehl.

Siehe auch

CanvasRenderingContext2D CanvasRenderingContext2D.drawImage() CanvasRenderingContext2D.save() CanvasRenderingContext2D.restore() CanvasRenderingContext2D.globalCompositeOperation CanvasRenderingContext2D.shadowBlur CanvasRenderingContext2D.getImageData()