SVGGeometryElement.getTotalLength() — Methode · JavaScript-Referenz

Signatur

SVGGeometryElement.prototype.getTotalLength()

Beschreibung

getTotalLength() liefert die Länge der Kontur eines SVG-Geometrie-Elements, also von <path>, <line>, <polyline>, <polygon>, <rect>, <circle> und <ellipse>. Der Wert wird in Benutzereinheiten angegeben, also im lokalen Koordinatensystem des Elements. Transformationen oder die Skalierung durch viewBox fließen nicht mit ein.

Am häufigsten nutzt man die Methode für „Line-Drawing“-Animationen. Man setzt stroke-dasharray und stroke-dashoffset auf die Gesamtlänge und animiert den Offset dann auf 0. So sieht es aus, als würde die Linie gezeichnet. Zusammen mit getPointAtLength() kann man außerdem Objekte an einem Pfad entlang bewegen oder einen Pfad in gleich lange Abschnitte teilen.

Das Attribut pathLength ändert den Rückgabewert von getTotalLength() nicht. Die Methode gibt immer die tatsächlich berechnete Länge zurück. pathLength skaliert nur die Berechnungen für Strichmuster und Textpfade. Weil die Länge numerisch angenähert wird, können sich die Werte zwischen Browsern leicht unterscheiden.

Rückgabewert

Typ

number

Beschreibung

Die Gesamtlänge der Kontur in Benutzereinheiten als Gleitkommazahl. Bei leeren Pfaden (z. B. ohne d-Attribut) ist der Wert 0.

Beispiele

Länge eines Pfads auslesen

const path = document.querySelector('#kurve');
// <path id="kurve" d="M 0 0 L 100 0 L 100 100" />
const laenge = path.getTotalLength();
console.log(`Pfadlänge: ${laenge}`);

Pfadlänge: 200

Linie „zeichnen“ mit stroke-dashoffset

const path = document.querySelector('#logo-pfad');
const laenge = path.getTotalLength();

// Strich unsichtbar machen: Lücke so lang wie der ganze Pfad
path.style.strokeDasharray = `${laenge}`;
path.style.strokeDashoffset = `${laenge}`;

// Offset mit der Web Animations API auf 0 animieren
path.animate(
  [{ strokeDashoffset: laenge }, { strokeDashoffset: 0 }],
  { duration: 2000, easing: 'ease-in-out', fill: 'forwards' }
);

Punkte in gleichen Abständen entlang eines Pfads

const path = document.querySelector('#route');
const laenge = path.getTotalLength();
const anzahl = 5;

const punkte = Array.from({ length: anzahl + 1 }, (_, i) => {
  const { x, y } = path.getPointAtLength((laenge / anzahl) * i);
  return { x: Math.round(x), y: Math.round(y) };
});
console.log(punkte);

[{x: 0, y: 0}, {x: 40, y: 0}, …] (abhängig vom Pfad)

Umfang eines Kreises

const kreis = document.querySelector('circle'); // r="50"
console.log(kreis.getTotalLength().toFixed(2));

314.16

// Wichtig · Fallstricke

Kompatibilität: Früher gab es die Methode nur auf SVGPathElement. Bei sehr alten Browsern (z. B. Safari < 12, Firefox < 57) fehlt sie für Formen wie <circle> oder <rect>, oder sie funktioniert dort nicht zuverlässig.
Transformationen werden ignoriert: transform, CSS-Skalierung und viewBox verändern die sichtbare Länge, aber nicht den Rückgabewert. Wenn du die Länge auf dem Bildschirm brauchst, rechne sie selbst mit getScreenCTM() um.
pathLength wirkt sich nicht auf den Rückgabewert aus. Setzt du z. B. pathLength=\"1\", kannst du für stroke-dasharray einfach 1 verwenden und brauchst getTotalLength() dann oft gar nicht.
Das Element muss im DOM sein und eine gültige Geometrie haben. Einige ältere Browser werfen bei Elementen, die nicht dargestellt werden (display: none), einen Fehler oder geben 0 zurück.
Performance: Bei komplexen Pfaden ist die Berechnung aufwendig. Speichere das Ergebnis zwischen, statt die Methode in jedem Animations-Frame neu aufzurufen.
Die Werte werden angenähert und können sich zwischen Browsern in den Nachkommastellen unterscheiden.

Siehe auch

SVGGeometryElement.getPointAtLength() SVGGeometryElement.pathLength SVGGeometryElement.isPointInStroke() SVGGeometryElement SVGPathElement Element.animate()