new Path2D() — Methode · JavaScript-Referenz

Signatur

new Path2D(path)

Beschreibung

Der Konstruktor new Path2D() erzeugt ein wiederverwendbares Pfadobjekt für die Canvas-2D-API. Statt Pfade bei jedem Zeichnen mit beginPath(), moveTo(), lineTo() usw. direkt im Kontext neu aufzubauen, beschreibt man die Geometrie einmal in einem Path2D-Objekt und übergibt es anschließend beliebig oft an ctx.fill(path), ctx.stroke(path), ctx.clip(path) oder ctx.isPointInPath(path, x, y).

Es gibt drei Varianten:

Ohne Argument: Es entsteht ein leerer Pfad, den man mit denselben Methoden wie im Kontext füllt (moveTo, lineTo, arc, rect, bezierCurveTo, roundRect …).
Mit einem Path2D: Es entsteht eine unabhängige Kopie. Spätere Änderungen an der Kopie wirken sich nicht auf das Original aus.
Mit einem String: Der String wird wie das d-Attribut eines SVG-<path>-Elements interpretiert. So lassen sich Icons und Formen aus SVG-Dateien direkt im Canvas zeichnen.

Besonders nützlich ist Path2D bei Animationen und interaktiven Grafiken. Man legt statische Formen einmal an, zeichnet sie in jedem Frame erneut und prüft Mausklicks per Trefferprüfung (Hit-Testing) mit isPointInPath() gegen genau denselben Pfad.

Parameter

Name	Typ	Default	Beschreibung
$path	Path2D \| string		Optional. Ein anderes `Path2D`-Objekt, das kopiert wird, oder ein String mit SVG-Pfaddaten (Syntax des `d`-Attributs, z. B. `"M10 10 h 80 v 80 h -80 Z"`). Ohne Argument entsteht ein leerer Pfad.

Rückgabewert

Typ

Path2D

Beschreibung

Ein neues Path2D-Objekt, das man an Zeichenmethoden des CanvasRenderingContext2D übergeben kann.

Beispiele

Leeren Pfad anlegen und mehrfach zeichnen

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

// Kreis einmal definieren …
const circle = new Path2D();
circle.arc(50, 50, 40, 0, Math.PI * 2);

// … und mehrfach nutzen
ctx.fillStyle = 'tomato';
ctx.fill(circle);
ctx.lineWidth = 4;
ctx.strokeStyle = '#333';
ctx.stroke(circle);

SVG-Pfaddaten direkt im Canvas zeichnen

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

// Herz-Icon aus einer SVG-Datei (d-Attribut)
const heart = new Path2D(
  'M50 30 C50 20 35 10 25 20 C15 30 20 45 50 70 C80 45 85 30 75 20 C65 10 50 20 50 30 Z'
);

ctx.fillStyle = 'crimson';
ctx.fill(heart);

// Verschoben ein zweites Mal zeichnen
ctx.save();
ctx.translate(100, 0);
ctx.fill(heart);
ctx.restore();

Pfad kopieren und erweitern

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

const base = new Path2D();
base.rect(10, 10, 80, 80);

// Unabhängige Kopie, die zusätzlich eine Diagonale enthält
const withCross = new Path2D(base);
withCross.moveTo(10, 10);
withCross.lineTo(90, 90);

ctx.stroke(base);      // nur Rechteck
ctx.translate(100, 0);
ctx.stroke(withCross); // Rechteck + Diagonale

Trefferprüfung bei Mausklicks

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

const button = new Path2D();
button.roundRect(20, 20, 120, 40, 8);
ctx.fillStyle = 'steelblue';
ctx.fill(button);

canvas.addEventListener('click', (event) => {
  const rect = canvas.getBoundingClientRect();
  const x = event.clientX - rect.left;
  const y = event.clientY - rect.top;
  if (ctx.isPointInPath(button, x, y)) {
    console.log('Button getroffen!');
  }
});

Button getroffen! (bei Klick innerhalb des Rechtecks)

// Wichtig · Fallstricke

Kein Fehler bei ungültigem SVG-String: Ist die Pfadsyntax fehlerhaft, wird der String nur bis zur fehlerhaften Stelle ausgewertet. Es gibt keine Exception, der Pfad bleibt dann unvollständig oder leer.
Nur Pfaddaten, keine Stile: Path2D speichert ausschließlich Geometrie. Farben, Linienbreite oder Transformationen aus dem SVG (fill, transform, viewBox) werden nicht übernommen. Diese setzt man über den Kontext, etwa mit ctx.translate() oder ctx.scale().
Canvas-Transformation beim Hit-Test: isPointInPath(path, x, y) berücksichtigt die aktuelle Transformationsmatrix des Kontexts. Hat man sie nach dem Zeichnen zurückgesetzt, stimmen die Koordinaten eventuell nicht mehr überein.
Kompatibilität: Der Konstruktor und fill()/stroke()/clip() mit Path2D-Argument funktionieren in allen modernen Browsern. Path2D.prototype.roundRect() ist neuer (ca. 2022/2023). In Web Workers steht Path2D zusammen mit OffscreenCanvas zur Verfügung. Den Internet Explorer gibt es nicht mehr, dort wurde Path2D nie unterstützt.
Ein Pfad kann mit addPath(otherPath, matrix) um weitere Pfade ergänzt werden, optional mit einer DOMMatrix als Transformation.

Siehe auch

Path2D Path2D.prototype.addPath() CanvasRenderingContext2D CanvasRenderingContext2D.prototype.fill() CanvasRenderingContext2D.prototype.stroke() CanvasRenderingContext2D.prototype.isPointInPath() CanvasRenderingContext2D.prototype.clip()