CanvasRenderingContext2D.beginPath() — Methode · JavaScript-Referenz

Signatur

CanvasRenderingContext2D.prototype.beginPath()

Beschreibung

beginPath() verwirft den aktuellen Pfad des Kontexts, also alle bisher mit moveTo(), lineTo(), arc(), rect() usw. angelegten Unterpfade. Danach beginnt ein leerer Pfad, den man neu aufbauen und anschließend mit stroke() oder fill() zeichnen kann.

Das ist nötig, weil stroke() und fill() den Pfad nicht leeren. Ohne beginPath() hängen neue Formen an den alten Pfad an. Beim nächsten stroke() werden dann alle früheren Formen erneut gezeichnet, und zwar mit der aktuellen Farbe und Linienbreite. Das kostet Leistung und sorgt für falsche Farben.

Faustregel: Rufe vor jeder eigenständigen Form, die eigene Stilwerte (strokeStyle, fillStyle, lineWidth) bekommen soll, zuerst beginPath() auf. Nach beginPath() gibt es keinen aktuellen Punkt mehr. Das erste lineTo() verhält sich deshalb wie ein moveTo().

Rückgabewert

Typ

void

Beschreibung

Kein Rückgabewert (undefined).

Beispiele

Zwei Linien in unterschiedlichen Farben

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

// Erste Linie: rot
ctx.beginPath();
ctx.strokeStyle = 'red';
ctx.moveTo(20, 20);
ctx.lineTo(200, 20);
ctx.stroke();

// Zweite Linie: blau – ohne beginPath() würde auch die erste Linie blau neu gezeichnet
ctx.beginPath();
ctx.strokeStyle = 'blue';
ctx.moveTo(20, 60);
ctx.lineTo(200, 60);
ctx.stroke();

Mehrere Kreise in einer Schleife zeichnen

const ctx = document.querySelector('canvas').getContext('2d');
const colors = ['#e63946', '#2a9d8f', '#e9c46a'];

colors.forEach((color, i) => {
  ctx.beginPath(); // jeder Kreis ist ein eigener Pfad
  ctx.arc(50 + i * 80, 100, 30, 0, Math.PI * 2);
  ctx.fillStyle = color;
  ctx.fill();
});

Animationsschleife mit sauberem Pfad pro Frame

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

const draw = () => {
  ctx.clearRect(0, 0, canvas.width, canvas.height);
  ctx.beginPath(); // verhindert, dass der Pfad mit jedem Frame weiterwächst
  ctx.arc(x, 75, 20, 0, Math.PI * 2);
  ctx.fill();
  x = (x + 2) % canvas.width;
  requestAnimationFrame(draw);
};

requestAnimationFrame(draw);

// Wichtig · Fallstricke

Häufigster Fehler: beginPath() wird vergessen. Der Pfad wächst dann mit jeder Form weiter, alte Formen werden mit dem neuen Stil übermalt, und in Animationen sinkt die Leistung spürbar.
clearRect() löscht nur Pixel, nicht den Pfad. beginPath() ist trotzdem nötig.
fillRect(), strokeRect() und fillText() nutzen den aktuellen Pfad nicht und verändern ihn auch nicht. rect() dagegen fügt dem Pfad etwas hinzu.
beginPath() ist nicht dasselbe wie closePath(): closePath() verbindet nur den letzten Punkt mit dem Startpunkt des Unterpfads.
Für wiederverwendbare Formen eignet sich ein Path2D-Objekt, das vom Pfad des Kontexts unabhängig ist.
Die Methode gibt es auch auf OffscreenCanvasRenderingContext2D. Sie wird von allen Browsern unterstützt.

Siehe auch

CanvasRenderingContext2D.closePath() CanvasRenderingContext2D.moveTo() CanvasRenderingContext2D.lineTo() CanvasRenderingContext2D.stroke() CanvasRenderingContext2D.fill() Path2D OffscreenCanvasRenderingContext2D.commit()