SVGPathElement.getTotalLength() — Methode · JavaScript-Referenz

Signatur

SVGPathElement.prototype.getTotalLength()

Beschreibung

getTotalLength() berechnet die geometrische Länge der gesamten Pfadkontur eines <path>-Elements. Die Länge wird in Benutzereinheiten angegeben, also im lokalen Koordinatensystem des Pfads. Transformationen (transform, viewBox-Skalierung) werden dabei nicht berücksichtigt.

Am häufigsten wird die Methode für Linien-Zeichen-Animationen benutzt: Man setzt stroke-dasharray und stroke-dashoffset auf die Pfadlänge und animiert den Offset dann auf 0. So entsteht der Eindruck, dass der Pfad Stück für Stück gezeichnet wird. Genauso nützlich ist sie in Kombination mit getPointAtLength(), um Objekte gleichmäßig entlang eines Pfads zu bewegen oder Punkte in festen Abständen abzutasten.

In SVG 2 ist die Methode in das Eltern-Interface SVGGeometryElement gewandert. Dadurch steht sie auch auf <circle>, <rect>, <line>, <polyline>, <polygon> und <ellipse> zur Verfügung. Das Attribut pathLength beeinflusst den Rückgabewert nicht. Die Methode liefert immer die tatsächlich berechnete Länge.

Rückgabewert

Typ

number

Beschreibung

Die Gesamtlänge des Pfads in Benutzereinheiten als Gleitkommazahl. Bei einem leeren Pfad (d fehlt oder ist leer) ist das Ergebnis 0.

Beispiele

Länge eines einfachen Pfads ermitteln

const svgNS = 'http://www.w3.org/2000/svg';
const svg = document.createElementNS(svgNS, 'svg');
const path = document.createElementNS(svgNS, 'path');
// Rechteck 100 × 50 als geschlossener Pfad
path.setAttribute('d', 'M 0 0 H 100 V 50 H 0 Z');
svg.appendChild(path);
document.body.appendChild(svg);

console.log(path.getTotalLength());

300

Linien-Zeichen-Animation mit stroke-dashoffset

// <svg viewBox="0 0 200 100"><path id="signatur" d="M10 80 C 40 10, 65 10, 95 80 S 150 150, 180 80" fill="none" stroke="black"/></svg>
const path = document.querySelector('#signatur');
const length = path.getTotalLength();

path.style.strokeDasharray = `${length}`;
path.style.strokeDashoffset = `${length}`;

path.animate(
  [{ strokeDashoffset: length }, { strokeDashoffset: 0 }],
  { duration: 2000, easing: 'ease-in-out', fill: 'forwards' }
);

Punkte in gleichen Abständen entlang eines Pfads abtasten

const path = document.querySelector('#route');
const total = path.getTotalLength();
const steps = 10;

const points = Array.from({ length: steps + 1 }, (_, i) => {
  const { x, y } = path.getPointAtLength((total / steps) * i);
  return { x: Math.round(x), y: Math.round(y) };
});

console.log(`Länge: ${total.toFixed(2)}`, points);

Länge: 412.37 [{x: 10, y: 80}, ...]

// Wichtig · Fallstricke

Transformationen werden ignoriert: Ist der Pfad per transform oder viewBox skaliert, weicht die sichtbare Länge in Bildschirmpixeln vom Rückgabewert ab. Für stroke-dasharray ist das aber genau richtig, weil beide im selben Koordinatensystem arbeiten.
pathLength wird nicht berücksichtigt: Die Methode liefert immer die tatsächlich berechnete Länge. Wer für Animationen pathLength=\"1\" setzt, braucht getTotalLength() dafür oft gar nicht.
Leere Pfade: Ohne gültiges d-Attribut ist das Ergebnis 0. Ältere Chromium-Versionen haben bei Elementen ohne Rendering (z. B. innerhalb von display: none) Fehler geworfen oder 0 geliefert.
Genauigkeit: Bei Bézier- und Bogensegmenten wird die Länge näherungsweise berechnet. Die Werte können sich zwischen Browsern in den Nachkommastellen leicht unterscheiden.
Performance: Bei sehr komplexen Pfaden ist der Aufruf verhältnismäßig teuer. Das Ergebnis sollte man zwischenspeichern und nicht in jedem Animationsframe neu berechnen.
Kompatibilität: Die Methode wird von allen modernen Browsern unterstützt. Für andere Formen als <path> ist sie erst über SVGGeometryElement verfügbar (in aktuellen Browsern ebenfalls überall).

Siehe auch

SVGPathElement SVGGeometryElement.getPointAtLength() SVGGeometryElement SVGGeometryElement.pathLength SVGGraphicsElement.getBBox() Element.animate()