SVGPathElement.pathLength — Eigenschaft · JavaScript-Referenz

Signatur

SVGPathElement.pathLength

Beschreibung

Die Eigenschaft pathLength spiegelt das SVG-Attribut pathLength eines <path>-Elements wider. Mit diesem Attribut legt man eine vom Autor festgelegte Gesamtlänge des Pfads fest. Der Browser rechnet dann alle Längenangaben entlang des Pfads, etwa stroke-dasharray, stroke-dashoffset oder das startOffset eines <textPath>, im Verhältnis zu diesem Wert um.

Die Eigenschaft selbst ist schreibgeschützt und liefert ein SVGAnimatedNumber-Objekt. Über baseVal liest oder setzt man den statischen Attributwert. animVal enthält den aktuell wirksamen Wert, auch während einer SMIL-Animation. Wer baseVal ändert, ändert damit direkt das Attribut im DOM.

Praktisch ist das vor allem für Linien-Zeichen-Animationen („Line Drawing“). Setzt man pathLength="100", lassen sich Strichmuster in Prozent angeben, ohne die tatsächliche Pfadlänge über getTotalLength() berechnen zu müssen. Das hilft besonders bei responsiven oder dynamisch erzeugten Pfaden.

Laut Spezifikation ist die Eigenschaft auf SVGGeometryElement definiert. SVGPathElement erbt sie von dort. Sie funktioniert daher genauso bei <circle>, <rect>, <line> und anderen Grundformen.

Rückgabewert

Typ

SVGAnimatedNumber

Beschreibung

Ein Objekt mit baseVal (Attributwert, beschreibbar, number) und animVal (aktuell wirksamer Wert, schreibgeschützt). Fehlt das Attribut, ist baseVal gleich 0.

Beispiele

Attributwert auslesen

// <svg><path id="linie" d="M10 10 L210 10" pathLength="100" /></svg>
const path = document.querySelector('#linie');

console.log(path.pathLength instanceof SVGAnimatedNumber);
console.log(path.pathLength.baseVal);
console.log(path.pathLength.animVal);

true 100 100

Autorenlänge im Vergleich zur echten Länge

const path = document.querySelector('#linie');

// getTotalLength() liefert immer die tatsächliche Länge in Benutzereinheiten
const echt = path.getTotalLength();
const autor = path.pathLength.baseVal || echt; // 0 = Attribut fehlt

console.log(`Echte Länge: ${echt}, Autorenlänge: ${autor}`);
console.log(`Skalierungsfaktor: ${echt / autor}`);

Echte Länge: 200, Autorenlänge: 100 Skalierungsfaktor: 2

Linien-Zeichen-Animation mit normierter Länge

const zeichnePfad = (path, dauerMs = 1500) => {
  // Länge auf 100 normieren – Dash-Werte gelten dann als Prozent
  path.pathLength.baseVal = 100;
  path.style.strokeDasharray = '100';
  path.style.strokeDashoffset = '100';

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

document.querySelectorAll('svg path.zeichnen').forEach((p) => zeichnePfad(p));
console.log(document.querySelector('path.zeichnen').getAttribute('pathLength'));

100

// Wichtig · Fallstricke

Nicht direkt zuweisen: path.pathLength = 50 bewirkt nichts, weil die Eigenschaft schreibgeschützt ist. Im strikten Modus wirft die Zuweisung einen TypeError. Ändern Sie stattdessen path.pathLength.baseVal oder rufen Sie setAttribute('pathLength', …) auf.
Fehlendes Attribut: Ohne pathLength-Attribut ist baseVal gleich 0. Das heißt nicht, dass der Pfad die Länge 0 hat. Die echte Länge liefert getTotalLength().
Kein Einfluss auf Geometrie-Methoden: getTotalLength() und getPointAtLength() rechnen nach SVG 2 immer mit der tatsächlichen Länge und ignorieren pathLength. Ältere Browser-Versionen verhielten sich hier teils anders.
Negative Werte sind ungültig. Der Wert 0 kann dazu führen, dass Strichmuster nicht dargestellt werden.
Kompatibilität: Wird von allen modernen Browsern unterstützt. Dass die Eigenschaft auch auf anderen Grundformen verfügbar ist (über SVGGeometryElement), gilt erst mit SVG 2. Sehr alte Browser kennen sie nur auf <path>.

Siehe auch

Element.animate() HTMLTextAreaElement.textLength SVGGeometryElement.pathLength SVGAElement.pathname SVGMPathElement.href