Path2D — Schnittstelle · JavaScript-Referenz

Signatur

interface Path2D

Beschreibung

Path2D gehört zur Canvas 2D API. Ein solches Objekt speichert eine Folge von Pfadbefehlen, also Linien, Bögen, Bézierkurven und Rechtecke, und hängt dabei nicht an einem bestimmten Zeichenkontext. Du kannst den Pfad deshalb einmal definieren und danach beliebig oft an CanvasRenderingContext2D.fill(), stroke(), clip(), isPointInPath() oder isPointInStroke() übergeben.

Ohne Path2D gibt es pro Kontext nur einen einzigen „aktuellen Pfad“. Ihn musst du bei jedem Frame mit beginPath() neu aufbauen. Mit Path2D kannst du mehrere Formen gleichzeitig vorhalten, zum Beispiel Spielfiguren, Symbole oder Klickbereiche. Das macht den Code übersichtlicher, und oft wird er auch schneller.

Der Konstruktor erzeugt je nach Argument:

einen leeren Pfad (ohne Argument),
eine Kopie eines anderen Path2D-Objekts,
einen Pfad aus einem SVG-Pfadstring (Syntax wie beim Attribut d eines SVG-<path>). Damit lassen sich Symbole direkt aus SVG-Dateien übernehmen.

Ein Path2D-Objekt hat die üblichen Pfadmethoden: moveTo(), lineTo(), bezierCurveTo(), quadraticCurveTo(), arc(), arcTo(), ellipse(), rect(), roundRect() und closePath(). Dazu kommt addPath(path, transform), das einen anderen Pfad anhängt und ihn dabei optional mit einer DOMMatrix transformiert.

Parameter

Name	Typ	Default	Beschreibung
$path	Path2D \| string		Optional. Ein anderes `Path2D`-Objekt, das kopiert wird, oder ein SVG-Pfadstring wie `"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 an Methoden wie fill(), stroke(), clip() und isPointInPath() des Kontexts übergeben werden kann.

Beispiele

Pfad anlegen und mehrfach zeichnen

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

// Wiederverwendbarer Kreis
const kreis = new Path2D();
kreis.arc(0, 0, 20, 0, Math.PI * 2);

// Gleichen Pfad an drei Positionen zeichnen
[50, 120, 190].forEach((x, i) => {
  ctx.save();
  ctx.translate(x, 60);
  ctx.fillStyle = ['tomato', 'gold', 'seagreen'][i];
  ctx.fill(kreis);
  ctx.stroke(kreis);
  ctx.restore();
});

SVG-Pfadstring als Symbol übernehmen

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

// Herz-Symbol direkt aus SVG-Pfaddaten
const herz = new Path2D(
  'M12 21 L10.5 19.6 C5.4 15 2 12 2 8.5 C2 5.4 4.4 3 7.5 3 ' +
  'C9.2 3 10.9 3.8 12 5.1 C13.1 3.8 14.8 3 16.5 3 ' +
  'C19.6 3 22 5.4 22 8.5 C22 12 18.6 15 13.5 19.6 Z'
);

ctx.scale(4, 4);
ctx.fillStyle = 'crimson';
ctx.fill(herz);

Klick-Erkennung mit isPointInPath

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

const button = new Path2D();
button.roundRect(20, 20, 160, 50, 12);
ctx.fillStyle = '#3366ff';
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)

Pfade kombinieren mit addPath und DOMMatrix

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

const quadrat = new Path2D();
quadrat.rect(0, 0, 40, 40);

const gruppe = new Path2D();
gruppe.addPath(quadrat);
// Kopie um 60px verschoben und um 45° gedreht anhängen
gruppe.addPath(quadrat, new DOMMatrix().translate(100, 20).rotate(45));

ctx.strokeStyle = 'black';
ctx.stroke(gruppe);

// Wichtig · Fallstricke

Koordinaten bei der Trefferprüfung: isPointInPath(path, x, y) prüft gegen die aktuelle Transformation des Kontexts. Die Mauskoordinaten musst du selbst in Canvas-Koordinaten umrechnen. Das betrifft CSS-Skalierung und devicePixelRatio.
Transformationen: Ein Path2D speichert seine Koordinaten unverändert. Wirksam wird die Transformation, die der Kontext beim Zeichnen gerade hat (translate, scale usw.). Soll ein Pfad dauerhaft verändert werden, nutze addPath(path, matrix).
Kein Zurücksetzen, kein Auslesen: Es gibt kein beginPath() für Path2D. Für eine neue Form legst du einfach ein neues Objekt an. Die gespeicherten Punkte lassen sich auch nicht auslesen oder serialisieren.
Kompatibilität: Alle aktuellen Browser unterstützen Path2D samt SVG-Strings, auch in OffscreenCanvas und Web Workern. roundRect() ist neuer (Chrome 99, Firefox 112, Safari 16). Den Internet Explorer musst du dagegen per Fallback abdecken. Ist ein SVG-Pfadstring ungültig, wirft der Konstruktor keinen Fehler: Der Pfad endet einfach ab der fehlerhaften Stelle.
Performance: Komplexe Pfade einmal als Path2D anzulegen und dann wiederzuverwenden ist meist günstiger, als sie in jedem Animationsframe neu aufzubauen.

Siehe auch

Attr Cache HID DataCue Gamepad