CanvasGradient.addColorStop() — Methode · JavaScript-Referenz

Signatur

CanvasGradient.prototype.addColorStop(offset, color)

Beschreibung

Die Methode addColorStop() legt fest, welche Farbe ein Farbverlauf an einer bestimmten Stelle hat. Ein CanvasGradient-Objekt entsteht über createLinearGradient(), createRadialGradient() oder createConicGradient() des 2D-Kontexts. Solange der Gradient keine Farbstopps hat, zeichnet er nichts; erst mit mindestens zwei Stopps bekommt man einen sichtbaren Übergang.

Der offset ist eine Zahl von 0 (Anfang des Verlaufs) bis 1 (Ende). Zwischen zwei Stopps interpoliert der Browser die Farben. Vor dem ersten Stopp gilt dessen Farbe, nach dem letzten Stopp die Farbe des letzten. Setzt man zwei Stopps auf denselben Offset, entsteht eine harte Kante ohne Übergang. Damit lassen sich zum Beispiel Streifen darstellen.

Der Gradient wird anschließend fillStyle oder strokeStyle zugewiesen. Die Koordinaten des Verlaufs beziehen sich auf das Koordinatensystem des Canvas und nicht auf die gezeichnete Form. Ein Gradient lässt sich wiederverwenden, einmal gesetzte Stopps kann man aber nicht wieder entfernen.

Parameter

Name	Typ	Default	Beschreibung
$offset Pflicht	number		Relative Position des Farbstopps von `0` bis `1` einschließlich. Werte außerhalb dieses Bereichs oder `NaN` lösen einen `IndexSizeError` aus.
$color Pflicht	string		Beliebiger CSS-Farbwert als Zeichenkette, z. B. `'red'`, `'#0af'`, `'rgb(0 128 255 / 50%)'` oder `'transparent'`. Ist der Wert nicht als Farbe lesbar, wird ein `SyntaxError` ausgelöst.

Rückgabewert

Typ

void

Beschreibung

Kein Rückgabewert (undefined). Die Methode ändert das Gradient-Objekt direkt und lässt sich deshalb nicht verketten.

Beispiele

Linearer Verlauf als Hintergrund

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

// Verlauf von links nach rechts über die ganze Breite
const gradient = ctx.createLinearGradient(0, 0, canvas.width, 0);
gradient.addColorStop(0, '#1e3c72');
gradient.addColorStop(0.5, '#2a5298');
gradient.addColorStop(1, '#6dd5ed');

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

Harte Kanten: Streifen mit doppelten Offsets

const ctx = document.querySelector('canvas').getContext('2d');
const streifen = ctx.createLinearGradient(0, 0, 300, 0);

const farben = ['#e63946', '#f1faee', '#457b9d'];
farben.forEach((farbe, i) => {
  const start = i / farben.length;
  const ende = (i + 1) / farben.length;
  // Zwei Stopps pro Farbe: kein weicher Übergang zwischen den Streifen
  streifen.addColorStop(start, farbe);
  streifen.addColorStop(ende, farbe);
});

ctx.fillStyle = streifen;
ctx.fillRect(0, 0, 300, 100);

Radialer Leuchteffekt mit Transparenz

const ctx = document.querySelector('canvas').getContext('2d');
const glow = ctx.createRadialGradient(150, 150, 0, 150, 150, 120);
glow.addColorStop(0, 'rgb(255 220 100 / 100%)');
glow.addColorStop(0.4, 'rgb(255 160 0 / 60%)');
glow.addColorStop(1, 'rgb(255 160 0 / 0%)'); // nach außen ausblenden

ctx.fillStyle = glow;
ctx.beginPath();
ctx.arc(150, 150, 120, 0, Math.PI * 2);
ctx.fill();

Fehlerbehandlung bei ungültigen Werten

const ctx = document.createElement('canvas').getContext('2d');
const g = ctx.createLinearGradient(0, 0, 100, 0);

try {
  g.addColorStop(1.5, 'red');
} catch (e) {
  console.log(e.name);
}

try {
  g.addColorStop(0.5, 'keine-farbe');
} catch (e) {
  console.log(e.name);
}

IndexSizeError SyntaxError

// Wichtig · Fallstricke

Wertebereich: Ein offset kleiner als 0 oder größer als 1 wird nicht auf den Bereich begrenzt, sondern löst eine IndexSizeError-DOMException aus. Berechnete Werte begrenzt man daher vorher, z. B. mit Math.min(1, Math.max(0, x)).
Ungültige Farben lösen einen SyntaxError aus. Anders als bei fillStyle werden sie nicht still ignoriert.
Transparenz: Blendet man mit 'transparent' aus, entspricht das rgba(0,0,0,0). Die Farben werden ohne vormultiplizierten Alphakanal interpoliert, deshalb kann ein grauer Übergang entstehen. Besser nimmt man dieselbe Farbe mit Alpha 0, z. B. rgb(255 160 0 / 0%).
Stopps mit gleichem Offset werden in der Reihenfolge ihres Hinzufügens angewendet. Das ergibt harte Kanten.
Einmal gesetzte Stopps lassen sich nicht entfernen. Für einen anderen Verlauf erstellt man einen neuen Gradienten.
Die Koordinaten des Gradienten gelten im aktuellen Koordinatensystem des Canvas zum Zeitpunkt des Zeichnens, einschließlich Transformationen. Sie beziehen sich nicht auf die Form selbst.
Kompatibilität: wird in allen Browsern unterstützt, auch in OffscreenCanvas und Web Workern. createConicGradient() ist neuer, seit etwa 2021/2022 in allen Browsern verfügbar.

Siehe auch

TaskAttributionTiming.toJSON() CanvasPattern.setTransform() InstallEvent.addRoutes() MediaStreamTrack.stop() Navigation.traverseTo()