CanvasRenderingContext2D.shadowOffsetY — Eigenschaft · JavaScript-Referenz

Signatur

CanvasRenderingContext2D.shadowOffsetY

Beschreibung

Die Eigenschaft shadowOffsetY des 2D-Kontexts bestimmt den vertikalen Versatz aller Schatten, die beim nachfolgenden Zeichnen entstehen. Das gilt für Formen, Pfade, Text und Bilder. Der Wert ist eine Gleitkommazahl. Positive Werte verschieben den Schatten nach unten, negative nach oben. Der Standardwert ist 0.

Meist setzt man shadowOffsetY zusammen mit shadowOffsetX, shadowBlur und shadowColor. So entstehen Effekte wie „schwebende“ Karten, Buttons mit Tiefe oder Text mit Schlagschatten. Ein Schatten wird nur gezeichnet, wenn shadowColor nicht vollständig transparent ist und mindestens einer der Werte shadowBlur, shadowOffsetX oder shadowOffsetY ungleich 0 ist.

Der Versatz wird im Koordinatenraum des Bitmaps angegeben. Die aktuelle Transformationsmatrix (scale(), rotate(), translate()) wirkt sich deshalb nicht auf ihn aus. Ein Schatten mit shadowOffsetY = 10 fällt also immer 10 Pixel nach unten, auch wenn der Kontext gedreht ist.

Rückgabewert

Typ

number

Beschreibung

Der aktuelle vertikale Schattenversatz als Gleitkommazahl. Der Standardwert ist 0. Beim Setzen werden Infinity, -Infinity und NaN stillschweigend ignoriert.

Beispiele

Einfacher Schlagschatten unter einem Rechteck

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

ctx.shadowColor = 'rgba(0, 0, 0, 0.5)';
ctx.shadowOffsetY = 12; // 12 px nach unten
ctx.shadowBlur = 4;

ctx.fillStyle = '#3b82f6';
ctx.fillRect(40, 30, 150, 80);

console.log(ctx.shadowOffsetY);

12

„Schwebende“ Karte mit Hover-Effekt

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

const drawCard = (lifted) => {
  ctx.clearRect(0, 0, canvas.width, canvas.height);
  ctx.save();
  ctx.shadowColor = 'rgba(0, 0, 0, 0.35)';
  ctx.shadowBlur = lifted ? 20 : 6;
  ctx.shadowOffsetY = lifted ? 14 : 3; // angehoben = größerer Versatz
  ctx.fillStyle = '#fff';
  ctx.fillRect(50, 40, 200, 120);
  ctx.restore(); // Schatten-Einstellungen wieder zurücksetzen
};

drawCard(false);
canvas.addEventListener('mouseenter', () => drawCard(true));
canvas.addEventListener('mouseleave', () => drawCard(false));

Negativer Versatz und Unabhängigkeit von der Transformation

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

ctx.shadowColor = 'crimson';
ctx.shadowOffsetY = -8; // Schatten nach oben

ctx.font = 'bold 32px sans-serif';
ctx.fillText('Hallo', 20, 60);

// Trotz Rotation fällt der Schatten weiterhin genau 8 px nach oben
ctx.translate(200, 60);
ctx.rotate(Math.PI / 4);
ctx.fillText('Gedreht', 0, 0);

ctx.shadowOffsetY = NaN; // wird ignoriert
console.log(ctx.shadowOffsetY);

-8

// Wichtig · Fallstricke

Kein Schatten sichtbar? Der Standardwert von shadowColor ist rgba(0, 0, 0, 0), also vollständig transparent. Ohne eine sichtbare Farbe hat shadowOffsetY keine Wirkung.
Schatten-Eigenschaften gehören zum Zeichenzustand und gelten für alle folgenden Zeichenoperationen. Kapseln Sie sie mit save()/restore(), sonst bekommen auch spätere Formen ungewollt einen Schatten.
Die Transformationsmatrix beeinflusst den Versatz nicht. Bei scale() für HiDPI-Displays (devicePixelRatio) muss man den Wert deshalb selbst umrechnen, damit er optisch gleich bleibt.
Nicht-endliche Werte (NaN, Infinity) werden ohne Fehlermeldung ignoriert. Der vorherige Wert bleibt dann erhalten.
Schatten, besonders mit shadowBlur, kosten beim Zeichnen spürbar Leistung. In Animationen mit vielen Objekten sollte man sie sparsam einsetzen oder vorberechnete Bilder nutzen.
Die Eigenschaft wird von allen modernen Browsern unterstützt und ist auch in OffscreenCanvasRenderingContext2D verfügbar.

Siehe auch

CanvasRenderingContext2D.shadowOffsetX CanvasRenderingContext2D.shadowBlur CanvasRenderingContext2D.shadowColor CanvasRenderingContext2D.save() CanvasRenderingContext2D.restore() CanvasRenderingContext2D