CanvasRenderingContext2D.createLinearGradient() — Methode · JavaScript-Referenz

Signatur

CanvasRenderingContext2D.prototype.createLinearGradient(x0, y0, x1, y1)

Beschreibung

Die Methode createLinearGradient() erzeugt einen linearen Farbverlauf, der entlang einer gedachten Linie zwischen Start- und Endpunkt verläuft. Der Verlauf selbst zeichnet noch nichts. Er ist ein CanvasGradient-Objekt, das du über addColorStop() mit Farben füllst und dann an fillStyle oder strokeStyle zuweist.

Die Koordinaten beziehen sich auf das Koordinatensystem der Zeichenfläche und nicht auf die Form, die später gefüllt wird. Wenn du ein Rechteck bei x = 200 zeichnest und der Verlauf nur von 0 bis 100 reicht, sieht das Rechteck einfarbig aus: Außerhalb der Linie wird die Farbe des ersten bzw. letzten Farbstopps einfach fortgesetzt. Senkrecht zur Verlaufslinie bleibt die Farbe gleich.

Typische Einsatzzwecke:

Hintergründe
Balken in Diagrammen
Glanz- und Schatteneffekte auf Schaltflächen
Himmel oder Horizont in Spielen
farbige Umrisslinien

Für die Richtung gilt: Ein waagerechter Verlauf hat gleiche y-Werte, ein senkrechter gleiche x-Werte, ein diagonaler unterschiedliche x- und y-Werte.

Parameter

Name	Typ	Beschreibung
$x0 Pflicht	number	x-Koordinate des Startpunkts der Verlaufslinie.
$y0 Pflicht	number	y-Koordinate des Startpunkts der Verlaufslinie.
$x1 Pflicht	number	x-Koordinate des Endpunkts der Verlaufslinie.
$y1 Pflicht	number	y-Koordinate des Endpunkts der Verlaufslinie.

Rückgabewert

Typ

CanvasGradient

Beschreibung

Ein neues CanvasGradient-Objekt ohne Farbstopps. Farben fügst du mit addColorStop(offset, color) hinzu.

Beispiele

Waagerechter Verlauf als Hintergrund

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

// Verlauf von links nach rechts über die gesamte Breite
const verlauf = ctx.createLinearGradient(0, 0, canvas.width, 0);
verlauf.addColorStop(0, '#1e3a8a');
verlauf.addColorStop(0.5, '#3b82f6');
verlauf.addColorStop(1, '#93c5fd');

ctx.fillStyle = verlauf;
ctx.fillRect(0, 0, canvas.width, canvas.height);
console.log(verlauf instanceof CanvasGradient);

true

Balkendiagramm mit Verlauf pro Balken

const ctx = document.querySelector('#diagramm').getContext('2d');
const werte = [120, 80, 150, 60];
const basis = 180;

werte.forEach((wert, i) => {
  const x = 20 + i * 50;
  const y = basis - wert;
  // Koordinaten an den einzelnen Balken anpassen, von oben nach unten
  const g = ctx.createLinearGradient(0, y, 0, basis);
  g.addColorStop(0, '#22c55e');
  g.addColorStop(1, '#14532d');
  ctx.fillStyle = g;
  ctx.fillRect(x, y, 40, wert);
});

Diagonaler Verlauf für eine Umrisslinie

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

const g = ctx.createLinearGradient(20, 20, 220, 120);
g.addColorStop(0, 'rgb(255 0 128)');
g.addColorStop(1, 'rgb(0 200 255)');

ctx.lineWidth = 8;
ctx.strokeStyle = g;
ctx.strokeRect(20, 20, 200, 100);

Harte Farbkante mit zwei Stopps an derselben Stelle

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

const g = ctx.createLinearGradient(0, 0, 0, 90);
g.addColorStop(0, 'black');
g.addColorStop(1 / 3, 'black');
g.addColorStop(1 / 3, 'red');
g.addColorStop(2 / 3, 'red');
g.addColorStop(2 / 3, 'gold');
g.addColorStop(1, 'gold');

ctx.fillStyle = g;
ctx.fillRect(0, 0, 150, 90);

// Wichtig · Fallstricke

Koordinaten gelten für die Zeichenfläche: Der Verlauf bezieht sich auf die Zeichenfläche (unter Berücksichtigung der aktuellen Transformation beim Füllen) und nicht auf die gefüllte Form. Wenn du eine Form verschiebst, musst du den Verlauf mitverschieben oder vor dem Zeichnen translate() verwenden.
Start- und Endpunkt identisch: Stimmen beide Punkte überein, wird nichts gemalt. Die Form bleibt dann transparent.
Fehler bei ungültigen Werten: Nicht endliche Werte (NaN, Infinity) lösen einen TypeError aus. Ein Offset außerhalb von 0–1 in addColorStop() löst einen IndexSizeError aus, eine ungültige Farbe einen SyntaxError.
Verläufe wiederverwenden: Ein Verlauf ohne Farbstopps malt transparent. Verläufe nicht in jedem Animationsbild neu erzeugen, wenn sie unverändert bleiben – einmal anlegen und wiederverwenden spart Rechenzeit.
Kompatibilität: Die Methode wird in allen Browsern unterstützt und ist auch in OffscreenCanvasRenderingContext2D (z. B. in Web Workern) verfügbar.

Siehe auch

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