CanvasRenderingContext2D.shadowBlur — Eigenschaft · JavaScript-Referenz

Signatur

CanvasRenderingContext2D.shadowBlur

Beschreibung

Mit shadowBlur bestimmen Sie, wie weich die Kanten eines Schattens sind, den der 2D-Kontext beim Zeichnen von Formen, Text und Bildern erzeugt. Der Wert ist eine Zahl ohne Einheit und gibt nicht direkt Pixel an. Die Spezifikation leitet daraus einen Gauß-Weichzeichner mit der Standardabweichung shadowBlur / 2 ab. Größere Werte ergeben weichere und breitere Schatten.

Die Eigenschaft wirkt nur zusammen mit einer sichtbaren shadowColor. Der Standardwert ist rgba(0, 0, 0, 0), also vollständig transparent. Ohne eigene Schattenfarbe bleibt shadowBlur deshalb wirkungslos. Mit shadowOffsetX und shadowOffsetY verschieben Sie den Schatten zusätzlich.

Typische Einsatzfälle sind Schlagschatten für Karten und Buttons, Leucht- bzw. Glow-Effekte (Offset 0, helle Farbe, hoher Blur) und weich abgesetzter Text über unruhigen Hintergründen.

shadowBlur gehört zum Zeichenzustand. Mit save() und restore() können Sie den Wert gezielt auf einzelne Zeichenoperationen begrenzen.

Parameter

Name	Typ	Default	Beschreibung
$value	number	0	Stärke der Unschärfe als nicht-negative Gleitkommazahl. Negative Werte, `Infinity` und `NaN` werden ignoriert, der bisherige Wert bleibt dann erhalten.

Rückgabewert

Typ

number

Beschreibung

Die aktuell eingestellte Unschärfe des Schattens (Standard: 0).

Beispiele

Einfacher weicher Schlagschatten

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

ctx.shadowColor = 'rgba(0, 0, 0, 0.5)';
ctx.shadowBlur = 15;
ctx.shadowOffsetX = 6;
ctx.shadowOffsetY = 6;

ctx.fillStyle = '#3498db';
ctx.fillRect(40, 40, 160, 100);

console.log(ctx.shadowBlur);

15

Glow-Effekt für Text, mit save()/restore() begrenzt

const ctx = document.querySelector('canvas').getContext('2d');
ctx.fillStyle = '#111';
ctx.fillRect(0, 0, 400, 200);

ctx.save();
ctx.font = 'bold 48px sans-serif';
ctx.fillStyle = '#fff';
ctx.shadowColor = '#0ff';
ctx.shadowBlur = 25;   // ohne Offset: Leuchten rundherum
ctx.fillText('NEON', 90, 120);
ctx.restore();

// Nach restore() sind die Schatten wieder aus
console.log(ctx.shadowBlur);

Ungültige Werte werden ignoriert

const ctx = document.createElement('canvas').getContext('2d');
ctx.shadowBlur = 10;
ctx.shadowBlur = -5;       // ignoriert
ctx.shadowBlur = NaN;      // ignoriert
ctx.shadowBlur = Infinity; // ignoriert
console.log(ctx.shadowBlur);

10

Animierter pulsierender Schatten

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

const draw = (t) => {
  ctx.clearRect(0, 0, canvas.width, canvas.height);
  ctx.shadowColor = 'rgba(255, 80, 0, 0.9)';
  ctx.shadowBlur = 10 + Math.sin(t / 300) * 10 + 10; // 10 bis 30
  ctx.fillStyle = '#ff5000';
  ctx.beginPath();
  ctx.arc(150, 100, 40, 0, Math.PI * 2);
  ctx.fill();
  requestAnimationFrame(draw);
};
requestAnimationFrame(draw);

// Wichtig · Fallstricke

Schattenfarbe nötig: Der Standardwert von shadowColor ist vollständig transparent. Ohne eigene Farbe ist kein Schatten zu sehen, auch nicht bei hohem shadowBlur.
Keine Pixelangabe: Der Wert ist eine Zahl ohne Einheit und wird nicht durch die aktuelle Transformationsmatrix beeinflusst. scale() vergrößert den Blur also nicht. Auf HiDPI-Canvas-Elementen, die mit devicePixelRatio skaliert werden, wirkt der Schatten deshalb schmaler. Passen Sie den Wert bei Bedarf manuell an.
Leistung: Große Blur-Werte sind aufwendig zu berechnen, vor allem bei vielen Objekten oder in Animationen. Rendern Sie statische Schatten einmal in ein Offscreen-Canvas und verwenden Sie das Ergebnis wieder. Setzen Sie shadowBlur nach der Nutzung zurück, am besten mit save()/restore().
Schatten wirken überall: Solange Schatten aktiv sind, bekommt jede weitere Zeichenoperation einen Schatten, auch drawImage() und stroke().
Kompatibilität: Wird in allen modernen Browsern unterstützt, auch in OffscreenCanvasRenderingContext2D. Das Ergebnis kann sich zwischen den Browsern leicht unterscheiden.
Als Alternative für komplexere Effekte gibt es ctx.filter = 'drop-shadow(...)'. Diese Eigenschaft wird in älteren Safari-Versionen nicht unterstützt.

Siehe auch

CanvasRenderingContext2D.shadowColor CanvasRenderingContext2D.shadowOffsetX CanvasRenderingContext2D.shadowOffsetY CanvasRenderingContext2D.filter CanvasRenderingContext2D.save() CanvasRenderingContext2D