CanvasRenderingContext2D.globalAlpha — Eigenschaft · JavaScript-Referenz

Signatur

CanvasRenderingContext2D.globalAlpha

Beschreibung

Die Eigenschaft globalAlpha des CanvasRenderingContext2D bestimmt die Deckkraft aller Zeichenoperationen, die nach dem Setzen ausgeführt werden. Das betrifft Füllungen (fillRect(), fill()), Konturen (stroke()), Text (fillText()) und Bilder (drawImage()). Der Wert liegt zwischen 0.0 (vollständig transparent) und 1.0 (vollständig deckend, Standard).

Der globale Alpha-Wert wird mit dem Alpha-Kanal der jeweiligen Farbe multipliziert. Setzt du also globalAlpha = 0.5 und zeichnest mit rgba(0, 0, 255, 0.5), ergibt sich eine effektive Deckkraft von 0.25.

Typische Anwendungsfälle sind Ein- und Ausblend-Animationen, halbtransparente Overlays, Wasserzeichen, Schatten- oder „Geister“-Effekte sowie das Zeichnen von Bildern mit reduzierter Deckkraft, ohne jede Farbe einzeln anpassen zu müssen. globalAlpha ist Teil des Zeichenzustands und wird daher von save() und restore() gesichert bzw. wiederhergestellt.

Parameter

Name	Typ	Default	Beschreibung
$value	number	1.0	Deckkraft zwischen `0.0` (transparent) und `1.0` (deckend). Werte außerhalb dieses Bereichs sowie `NaN` und `Infinity` werden ignoriert.

Rückgabewert

Typ

number

Beschreibung

Der aktuell gesetzte globale Alpha-Wert im Bereich 0.0 bis 1.0.

Beispiele

Halbtransparente, überlappende Rechtecke

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

ctx.globalAlpha = 0.5;

ctx.fillStyle = 'red';
ctx.fillRect(20, 20, 100, 100);

ctx.fillStyle = 'blue';
ctx.fillRect(70, 70, 100, 100); // Überlappung erscheint violett

console.log(ctx.globalAlpha);

0.5

Wasserzeichen mit save()/restore() begrenzen

const ctx = document.querySelector('canvas').getContext('2d');
const img = new Image();
img.src = 'foto.jpg';

img.addEventListener('load', () => {
  ctx.drawImage(img, 0, 0, 400, 300);

  ctx.save();
  ctx.globalAlpha = 0.3; // gilt nur bis restore()
  ctx.font = 'bold 32px sans-serif';
  ctx.fillStyle = 'white';
  ctx.fillText('© programmierung.net', 40, 280);
  ctx.restore();

  console.log(ctx.globalAlpha); // wieder Standardwert
});

1

Einblend-Animation mit requestAnimationFrame

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

const draw = () => {
  ctx.clearRect(0, 0, canvas.width, canvas.height);
  ctx.globalAlpha = alpha;
  ctx.fillStyle = 'teal';
  ctx.beginPath();
  ctx.arc(150, 75, 50, 0, Math.PI * 2);
  ctx.fill();

  alpha = Math.min(alpha + 0.02, 1);
  if (alpha < 1) requestAnimationFrame(draw);
};

requestAnimationFrame(draw);

Ungültige Werte werden ignoriert

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

ctx.globalAlpha = 0.4;
ctx.globalAlpha = 2;    // außerhalb des Bereichs
ctx.globalAlpha = -1;   // außerhalb des Bereichs
ctx.globalAlpha = NaN;  // ungültig

console.log(ctx.globalAlpha);

0.4

// Wichtig · Fallstricke

Wirkt nur auf nachfolgende Operationen: Bereits Gezeichnetes wird nicht verändert. Um den gesamten Canvas nachträglich transparent zu machen, nutze CSS opacity oder zeichne den Inhalt erneut.
Multiplikation mit Farb-Alpha: globalAlpha wird mit dem Alpha von fillStyle/strokeStyle bzw. dem Bild-Alpha multipliziert – nicht ersetzt.
Zustand vergessen zurückzusetzen ist ein häufiger Fehler: Ohne save()/restore() oder explizites globalAlpha = 1 werden alle folgenden Zeichnungen transparent.
Ungültige Werte (< 0, > 1, NaN, Infinity) werden stillschweigend ignoriert; es wird kein Fehler geworfen.
Überlappende Pfadsegmente innerhalb eines stroke()-Aufrufs werden nicht doppelt abgedunkelt; separate Aufrufe dagegen schon.
Kompatibilität: In allen modernen Browsern unterstützt, ebenso in OffscreenCanvasRenderingContext2D (Web Worker).

Siehe auch

CanvasRenderingContext2D CanvasRenderingContext2D.globalCompositeOperation CanvasRenderingContext2D.fillStyle CanvasRenderingContext2D.save() CanvasRenderingContext2D.restore() CanvasRenderingContext2D.drawImage()