Signatur
Beschreibung
CanvasGradient steht für einen Farbverlauf im 2D-Canvas. Einen eigenen Konstruktor gibt es nicht. Instanzen erzeugt man immer über die Fabrikmethoden des Kontexts: createLinearGradient() für lineare Verläufe, createRadialGradient() für kreisförmige Verläufe zwischen zwei Kreisen und createConicGradient() für kegelförmige Verläufe um einen Mittelpunkt, zum Beispiel für Farbräder oder Tortendiagramme.
Das Objekt hat genau eine Methode: addColorStop(offset, color). Damit legt man fest, welche Farbe an welcher relativen Position (0 bis 1) im Verlauf liegt. Zwischen den Farbstopps wird die Farbe interpoliert. Wie weit die Farbstopps auseinanderliegen und wie der Verlauf ausgerichtet ist, ergibt sich aus den Koordinaten bei der Erzeugung.
Die Koordinaten des Verlaufs gelten im Koordinatensystem des Canvas und nicht relativ zur gezeichneten Form. Ein Verlauf von (0,0) nach (200,0) sieht auf einem Rechteck bei x = 300 daher einfarbig aus. Transformationen wie translate() oder scale() wirken beim Zeichnen auch auf den Verlauf. Ein Verlaufsobjekt lässt sich für beliebig viele Zeichenoperationen wiederverwenden.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $offset Pflicht | number | Parameter von addColorStop(): Position des Farbstopps zwischen 0 (Anfang) und 1 (Ende). Werte außerhalb dieses Bereichs lösen einen IndexSizeError aus. |
|
| $color Pflicht | string | Parameter von addColorStop(): eine gültige CSS-Farbe, z. B. '#ff0000', 'rgb(0 128 255 / 50%)' oder 'transparent'. Ungültige Werte lösen einen SyntaxError aus. |
Rückgabewert
addColorStop() gibt nichts zurück. Die Methode verändert das Verlaufsobjekt direkt.Beispiele
Linearer Verlauf als Hintergrund
const canvas = document.querySelector('canvas');
const ctx = canvas.getContext('2d');
// Verlauf von links nach rechts über die gesamte 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);
console.log(gradient instanceof CanvasGradient);Radialer Verlauf für einen 3D-Kugeleffekt
const ctx = document.querySelector('canvas').getContext('2d');
// Innerer Kreis leicht versetzt als Lichtpunkt, äußerer Kreis = Kugelrand
const sphere = ctx.createRadialGradient(80, 80, 10, 100, 100, 70);
sphere.addColorStop(0, '#ffffff');
sphere.addColorStop(0.3, '#ff6b6b');
sphere.addColorStop(1, '#8b0000');
ctx.fillStyle = sphere;
ctx.beginPath();
ctx.arc(100, 100, 70, 0, Math.PI * 2);
ctx.fill();Konischer Verlauf als Farbrad
const ctx = document.querySelector('canvas').getContext('2d');
// Startwinkel 0, Mittelpunkt (150, 150)
const wheel = ctx.createConicGradient(0, 150, 150);
const hues = [0, 60, 120, 180, 240, 300, 360];
hues.forEach((hue, i) => {
wheel.addColorStop(i / (hues.length - 1), `hsl(${hue} 100% 50%)`);
});
ctx.fillStyle = wheel;
ctx.beginPath();
ctx.arc(150, 150, 120, 0, Math.PI * 2);
ctx.fill();Verlauf als Konturfarbe und Fehlerbehandlung
const ctx = document.querySelector('canvas').getContext('2d');
const stroke = ctx.createLinearGradient(20, 0, 280, 0);
stroke.addColorStop(0, 'orange');
stroke.addColorStop(1, 'purple');
ctx.lineWidth = 12;
ctx.strokeStyle = stroke;
ctx.strokeRect(20, 20, 260, 120);
try {
stroke.addColorStop(1.5, 'red');
} catch (err) {
console.log(err.name);
}// Wichtig · Fallstricke
- Kein Konstruktor:
new CanvasGradient()löst einenTypeErroraus. Verläufe entstehen nur übercreateLinearGradient(),createRadialGradient()odercreateConicGradient(). - Canvas-Koordinaten: Die Positionen des Verlaufs beziehen sich auf das Canvas und nicht auf die Form. Wenn Formen an anderer Stelle liegen, muss man die Koordinaten anpassen oder mit
translate()arbeiten. - Nicht auslesbar: Farbstopps lassen sich weder abfragen noch entfernen. Für Änderungen erzeugt man einen neuen Verlauf.
- Gleicher Offset: Zwei Farbstopps mit demselben Offset ergeben einen harten Farbwechsel. So lassen sich Streifen zeichnen.
- Ohne Farbstopps zeichnet ein Verlauf nichts, das Ergebnis ist transparent schwarz. Bei
createLinearGradient()mit identischem Start- und Endpunkt wird ebenfalls nichts gezeichnet. - Kompatibilität: Lineare und radiale Verläufe funktionieren in allen Browsern und auch in
OffscreenCanvas.createConicGradient()gibt es erst ab Chrome 99, Firefox 112 und Safari 16.1. Bei Bedarf vorher prüfen, ob die Methode vorhanden ist:'createConicGradient' in ctx. - Leistung: Verläufe am besten einmal erzeugen und in Animationsschleifen wiederverwenden, statt sie in jedem Frame neu zu erstellen.