SVGPathElement — Schnittstelle · JavaScript-Referenz

Signatur

interface SVGPathElement extends SVGGeometryElement

Beschreibung

SVGPathElement ist die DOM-Schnittstelle für das SVG-Element <path>, mit dem sich beliebige Formen aus Linien, Bögen und Bézierkurven beschreiben lassen. Die Form selbst steht im Attribut d (z. B. M 10 10 L 90 90). Das Interface erbt von SVGGeometryElement → SVGGraphicsElement → SVGElement → Element.

Die wichtigsten Fähigkeiten stammen aus SVGGeometryElement:

getTotalLength() – liefert die berechnete Gesamtlänge des Pfads in Benutzereinheiten.
getPointAtLength(distance) – liefert einen DOMPoint an einer bestimmten Stelle entlang des Pfads.
isPointInFill(point) / isPointInStroke(point) – prüfen, ob ein Punkt in der Füllung bzw. Kontur liegt.
pathLength – ein SVGAnimatedNumber, der die vom Autor angegebene Referenzlänge widerspiegelt.

Typische Einsatzgebiete sind „Linien-Zeichnen“-Animationen per stroke-dasharray/stroke-dashoffset, das Bewegen von Objekten entlang einer Kurve, Trefferprüfungen bei interaktiven Grafiken sowie das dynamische Erzeugen von Diagrammen. Neue Pfade erzeugt man mit document.createElementNS("http://www.w3.org/2000/svg", "path") und setzt die Geometrie über setAttribute("d", …).

Rückgabewert

Typ

SVGPathElement

Beschreibung

Instanzen erhält man über document.createElementNS() oder durch Abfrage vorhandener <path>-Elemente (z. B. querySelector("path")). Ein direkter Konstruktor existiert nicht.

Beispiele

Pfad dynamisch erzeugen und einfügen

const SVG_NS = "http://www.w3.org/2000/svg";
const svg = document.createElementNS(SVG_NS, "svg");
svg.setAttribute("viewBox", "0 0 100 100");

const path = document.createElementNS(SVG_NS, "path");
path.setAttribute("d", "M 10 80 Q 50 10 90 80");
path.setAttribute("fill", "none");
path.setAttribute("stroke", "tomato");
path.setAttribute("stroke-width", "3");

svg.append(path);
document.body.append(svg);

console.log(path instanceof SVGPathElement);
console.log(path instanceof SVGGeometryElement);

true true

Linien-Zeichnen-Animation mit getTotalLength()

const path = document.querySelector("#signatur");
const length = path.getTotalLength();

// Strich so lang wie der Pfad, komplett "versteckt"
path.style.strokeDasharray = `${length}`;
path.style.strokeDashoffset = `${length}`;

// Offset auf 0 animieren -> Pfad wird sichtbar "gezeichnet"
path.animate(
  [{ strokeDashoffset: length }, { strokeDashoffset: 0 }],
  { duration: 2000, easing: "ease-in-out", fill: "forwards" }
);

console.log(`Pfadlänge: ${length.toFixed(1)}`);

Pfadlänge: 123.4 (abhängig vom Pfad)

Objekt entlang eines Pfads bewegen (getPointAtLength)

const path = document.querySelector("#bahn");
const dot = document.querySelector("#punkt"); // ein <circle>
const total = path.getTotalLength();
const dauer = 3000;
let start;

const frame = (t) => {
  start ??= t;
  const progress = ((t - start) % dauer) / dauer;
  const { x, y } = path.getPointAtLength(progress * total);
  dot.setAttribute("cx", x);
  dot.setAttribute("cy", y);
  requestAnimationFrame(frame);
};

requestAnimationFrame(frame);

Trefferprüfung mit isPointInFill()

const svg = document.querySelector("svg");
const path = svg.querySelector("path");

svg.addEventListener("click", (event) => {
  // Bildschirmkoordinaten in SVG-Benutzerkoordinaten umrechnen
  const pt = new DOMPoint(event.clientX, event.clientY)
    .matrixTransform(path.getScreenCTM().inverse());

  console.log(path.isPointInFill(pt) ? "Treffer in der Fläche" : "Daneben");
});

Treffer in der Fläche // bzw. "Daneben"

// Wichtig · Fallstricke

Namensraum beachten: document.createElement(\"path\") erzeugt ein wirkungsloses HTMLUnknownElement. Immer createElementNS(\"http://www.w3.org/2000/svg\", \"path\") verwenden.
Veraltete API: Die SVG-1.1-Methoden getPathSegAtLength(), createSVGPathSeg…() sowie pathSegList wurden aus Chrome und Firefox entfernt. Die SVG-2-Methoden getPathData()/setPathData() sind kaum implementiert – Pfaddaten daher als String über das Attribut d lesen und schreiben.
pathLength-Attribut: Setzt der Autor pathLength, beziehen sich stroke-dasharray-Werte auf diese Referenzlänge. getTotalLength() liefert dennoch die tatsächlich berechnete Länge, getPointAtLength() arbeitet ebenfalls mit echten Einheiten.
Transformationen: Längen und Punkte gelten im lokalen Koordinatensystem des Pfads; transform-Attribute oder CSS-Transformationen fließen nicht ein. Für Bildschirmkoordinaten getScreenCTM() nutzen.
Performance: getTotalLength() kann bei komplexen Pfaden teuer sein – Ergebnis zwischenspeichern, statt es in jedem Animationsframe neu zu berechnen.
Ein leerer oder ungültiger d-Wert führt zu Länge 0; ältere Browser warfen bei getPointAtLength() auf leeren Pfaden teils Ausnahmen.

Siehe auch

SVGGeometryElement SVGGeometryElement.getTotalLength() SVGGeometryElement.getPointAtLength() SVGGeometryElement.isPointInFill() SVGElement Document.createElementNS()