CanvasRenderingContext2D.createRadialGradient() — Methode · JavaScript-Referenz

Signatur

CanvasRenderingContext2D.prototype.createRadialGradient(x0, y0, r0, x1, y1, r1)

Beschreibung

Die Methode createRadialGradient() legt einen radialen Farbverlauf an. Er wird durch zwei Kreise festgelegt: einen Startkreis (x0, y0, r0) und einen Endkreis (x1, y1, r1). Die Farben laufen dabei vom Rand des Startkreises bis zum Rand des Endkreises.

Zurück kommt ein CanvasGradient-Objekt, das zunächst keine Farben hat. Farbstopps fügt man mit addColorStop(offset, color) hinzu. Der Offset liegt zwischen 0 (Startkreis) und 1 (Endkreis). Danach weist man den Verlauf fillStyle oder strokeStyle zu.

Typische Anwendungen sind Lichtkegel, Glanzpunkte auf Kugeln, Vignetten, Glüheffekte und weiche Pinselspitzen. Liegen die Mittelpunkte der beiden Kreise nicht übereinander, entsteht ein Verlauf mit versetztem Fokus. So lässt sich zum Beispiel ein 3D-Effekt erzeugen.

Die Koordinaten beziehen sich auf das Koordinatensystem der Zeichenfläche (Canvas). Sie sind nicht relativ zur gezeichneten Form. Maßgeblich ist die Transformation, die beim Zeichnen aktiv ist, nicht die beim Erstellen des Verlaufs. Man sollte den Verlauf daher passend zur Position der Form berechnen.

Parameter

Name	Typ	Beschreibung
$x0 Pflicht	number	x-Koordinate des Mittelpunkts des Startkreises.
$y0 Pflicht	number	y-Koordinate des Mittelpunkts des Startkreises.
$r0 Pflicht	number	Radius des Startkreises. Darf nicht negativ sein.
$x1 Pflicht	number	x-Koordinate des Mittelpunkts des Endkreises.
$y1 Pflicht	number	y-Koordinate des Mittelpunkts des Endkreises.
$r1 Pflicht	number	Radius des Endkreises. Darf nicht negativ sein.

Rückgabewert

Typ

CanvasGradient

Beschreibung

Ein undurchsichtiges CanvasGradient-Objekt. Farbstopps fügt man mit addColorStop() hinzu.

Beispiele

Kugel mit Glanzpunkt

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

// Startkreis leicht nach oben links versetzt → 3D-Eindruck
const gradient = ctx.createRadialGradient(80, 80, 10, 100, 100, 70);
gradient.addColorStop(0, '#ffffff');
gradient.addColorStop(0.3, '#4da3ff');
gradient.addColorStop(1, '#003366');

ctx.fillStyle = gradient;
ctx.beginPath();
ctx.arc(100, 100, 70, 0, Math.PI * 2);
ctx.fill();

Vignette über ein Foto legen

const canvas = document.querySelector('#photo');
const ctx = canvas.getContext('2d');
const { width, height } = canvas;

const img = new Image();
img.src = 'landschaft.jpg';
await img.decode();
ctx.drawImage(img, 0, 0, width, height);

const cx = width / 2;
const cy = height / 2;
const outer = Math.hypot(cx, cy); // bis in die Ecken

const vignette = ctx.createRadialGradient(cx, cy, outer * 0.4, cx, cy, outer);
vignette.addColorStop(0, 'rgba(0, 0, 0, 0)');
vignette.addColorStop(1, 'rgba(0, 0, 0, 0.7)');

ctx.fillStyle = vignette;
ctx.fillRect(0, 0, width, height);

Glühender Lichtpunkt, der der Maus folgt

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

const drawGlow = (x, y) => {
  ctx.fillStyle = '#111';
  ctx.fillRect(0, 0, canvas.width, canvas.height);

  // Verlauf bei jeder Bewegung neu berechnen – Koordinaten sind absolut
  const glow = ctx.createRadialGradient(x, y, 0, x, y, 120);
  glow.addColorStop(0, 'rgba(255, 220, 120, 1)');
  glow.addColorStop(1, 'rgba(255, 220, 120, 0)');

  ctx.fillStyle = glow;
  ctx.fillRect(x - 120, y - 120, 240, 240);
};

canvas.addEventListener('pointermove', (e) => {
  const rect = canvas.getBoundingClientRect();
  drawGlow(e.clientX - rect.left, e.clientY - rect.top);
});

Fehlerfall: negativer Radius

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

try {
  ctx.createRadialGradient(50, 50, -5, 50, 50, 40);
} catch (err) {
  console.log(err.name);
}

IndexSizeError

// Wichtig · Fallstricke

Negative Radien lösen eine DOMException vom Typ IndexSizeError aus.
Nicht endliche Werte (NaN, Infinity) lösen einen TypeError aus.
Absolute Koordinaten: Der Verlauf hängt nicht an der Form. Wird die Form verschoben, muss man auch den Verlauf neu erstellen oder mit translate() arbeiten.
Ohne Farbstopps ist der Verlauf transparent und es wird nichts sichtbar gezeichnet.
Außerhalb der Kreise wird die Farbe des ersten bzw. letzten Stopps fortgesetzt. Ein Verlauf wiederholt sich nicht, anders als repeating-radial-gradient in CSS.
Startkreis nicht vollständig im Endkreis: Es entsteht ein kegelförmiger Verlauf, der oft unerwartet aussieht. Für normale Effekte sollte der Startkreis im Endkreis liegen.
Performance: Wenn sich Position und Farben nicht ändern, kann man einen Verlauf zwischenspeichern und wiederverwenden. Das Neuerstellen pro Frame ist aber meist unkritisch.
Kompatibilität: Wird in allen Browsern unterstützt, auch in OffscreenCanvasRenderingContext2D (Web Worker).

Siehe auch

CanvasRenderingContext2D.createConicGradient() CanvasRenderingContext2D.createLinearGradient() CanvasRenderingContext2D.createImageData() CanvasRenderingContext2D.createPattern() CanvasRenderingContext2D.clearRect()