Path2D.addPath() — Methode · JavaScript-Referenz

Signatur

Path2D.prototype.addPath(path, transform)

Beschreibung

addPath() kopiert alle Unterpfade eines anderen Path2D-Objekts in den Pfad, auf dem die Methode aufgerufen wird. Der Quellpfad selbst bleibt dabei unverändert. So lassen sich wiederverwendbare Formen wie Icons, Symbole oder Kacheln einmal definieren und dann zu größeren zusammengesetzten Pfaden kombinieren.

Über den optionalen zweiten Parameter transform kann der hinzugefügte Pfad vor dem Einfügen verschoben, skaliert, gedreht oder geschert werden. Das ist praktisch, um dieselbe Grundform mehrfach an verschiedenen Positionen in einen einzigen Pfad zu übernehmen. Danach reicht ein einzelner Aufruf von fill() oder stroke(), und das ist deutlich schneller als viele einzelne Zeichenaufrufe.

Wichtig: Die Transformation wirkt nur auf den hinzugefügten Pfad. Der Zielpfad und die aktuelle Transformation des Zeichenkontexts werden davon nicht beeinflusst. Beim späteren Zeichnen mit ctx.fill(path) gilt zusätzlich die Transformation des Kontexts (ctx.setTransform()).

Parameter

Name	Typ	Default	Beschreibung
$path Pflicht	Path2D		Der Pfad, dessen Unterpfade angehängt werden. Er wird kopiert und bleibt selbst unverändert.
$transform	DOMMatrix \| DOMMatrix2DInit	Identitätsmatrix	Optionale Transformationsmatrix, die vor dem Einfügen auf `path` angewendet wird. Gültig sind z. B. `new DOMMatrix()` oder ein einfaches Objekt wie `{ e: 50, f: 20 }`.

Rückgabewert

Typ

void

Beschreibung

Kein Rückgabewert (undefined). Der Zielpfad wird direkt verändert.

Beispiele

Zwei Pfade kombinieren und gemeinsam füllen

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

const kreis = new Path2D();
kreis.arc(60, 60, 40, 0, Math.PI * 2);

const gesamt = new Path2D();
gesamt.rect(120, 20, 80, 80);
gesamt.addPath(kreis); // Kreis anhängen

ctx.fillStyle = 'steelblue';
ctx.fill(gesamt); // ein einziger Zeichenaufruf

Grundform mehrfach mit DOMMatrix verschoben einfügen

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

// Stern-Icon einmal definieren
const stern = new Path2D('M10 0 L13 7 L20 7 L14 11 L16 18 L10 14 L4 18 L6 11 L0 7 L7 7 Z');

const sterne = new Path2D();
for (let i = 0; i < 5; i++) {
  const m = new DOMMatrix().translate(i * 30 + 10, 20);
  sterne.addPath(stern, m);
}

ctx.fillStyle = 'gold';
ctx.fill(sterne);
ctx.strokeStyle = 'darkorange';
ctx.stroke(sterne);

Gedreht und skaliert einfügen (mit Objekt-Literal)

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

const pfeil = new Path2D();
pfeil.moveTo(0, -10);
pfeil.lineTo(20, 0);
pfeil.lineTo(0, 10);
pfeil.closePath();

const ziel = new Path2D();
// einfaches Matrix-Objekt: Verschiebung um (100, 50)
ziel.addPath(pfeil, { e: 100, f: 50 });
// gedreht um 90° und doppelt so groß
ziel.addPath(pfeil, new DOMMatrix().translate(200, 50).rotate(90).scale(2));

ctx.fill(ziel);

// Wichtig · Fallstricke

Kopie statt Referenz: Wenn du den Quellpfad nach dem Aufruf von addPath() änderst, wirkt sich das nicht auf den Zielpfad aus.
Kein automatisches Verbinden: Die Unterpfade werden unabhängig angehängt. Zwischen dem letzten Punkt des Zielpfads und dem Anfang des hinzugefügten Pfads entsteht keine Linie.
Füllregel: Überlappende Teilpfade können bei fill(path, 'evenodd') Löcher erzeugen. Mit der Standardregel 'nonzero' hängt das Ergebnis von der Zeichenrichtung ab.
Ungültige Matrix: Wenn das transform-Objekt widersprüchliche Werte enthält (z. B. a und m11 verschieden), wird ein TypeError ausgelöst. Ist path kein Path2D, gibt es ebenfalls einen TypeError.
Kompatibilität: In allen aktuellen Browsern verfügbar, auch in OffscreenCanvas und Web Workern. Ältere Browserversionen erwarteten als zweiten Parameter ein SVGMatrix. Bei sehr alten Versionen fehlt die Methode ganz, deshalb vorher mit 'addPath' in Path2D.prototype prüfen.
Leistung: Viele gleiche Formen in einem Pfad zu sammeln und einmal zu zeichnen ist meist schneller als viele einzelne fill()-Aufrufe.

Siehe auch

new Path2D() CanvasRenderingContext2D.fill() CanvasRenderingContext2D.stroke() CanvasRenderingContext2D.setTransform() PushMessageData.json()