SVGGeometryElement.pathLength — Eigenschaft · JavaScript-Referenz

Signatur

readonly SVGGeometryElement.pathLength: SVGAnimatedNumber

Beschreibung

Die schreibgeschützte Eigenschaft pathLength eines SVGGeometryElement (z. B. <path>, <circle>, <rect>, <line>, <polyline>) gibt ein SVGAnimatedNumber-Objekt zurück. Es spiegelt das SVG-Attribut pathLength wider. Mit baseVal liest oder setzt man den Attributwert, animVal enthält den aktuellen, eventuell durch SMIL animierten Wert.

Wichtig: pathLength ist nicht die tatsächlich berechnete Länge der Geometrie. Es ist eine Angabe des Autors, welche Gesamtlänge der Pfad haben soll. Der Browser skaliert dann alle Längenangaben entlang des Pfades mit dem Faktor getTotalLength() / pathLength. Das betrifft stroke-dasharray, stroke-dashoffset, startOffset bei <textPath> und Marker-Positionen. Die echte Länge liefert getTotalLength().

Typischer Einsatz: Mit pathLength="100" oder pathLength="1" werden Strich-Animationen unabhängig von der tatsächlichen Pfadgröße. Ein Wert von stroke-dasharray: 100 deckt dann immer genau den ganzen Pfad ab, egal ob er 50 oder 5000 Einheiten lang ist.

Rückgabewert

Typ

SVGAnimatedNumber

Beschreibung

Objekt mit baseVal (number, beschreibbar: der Wert des Attributs pathLength) und animVal (number, nur lesbar: der aktuell animierte Wert). Fehlt das Attribut, ist baseVal 0.

Beispiele

Attributwert auslesen und mit der echten Länge vergleichen

const svgNS = 'http://www.w3.org/2000/svg';
const svg = document.createElementNS(svgNS, 'svg');
const path = document.createElementNS(svgNS, 'path');
path.setAttribute('d', 'M 0 0 L 300 0');
path.setAttribute('pathLength', '100');
svg.append(path);
document.body.append(svg);

console.log(path.pathLength.baseVal);   // Autor-Vorgabe
console.log(path.getTotalLength());     // tatsächliche Länge
console.log(path.pathLength.animVal);

100 300 100

Fehlendes Attribut erkennen

const circle = document.createElementNS('http://www.w3.org/2000/svg', 'circle');
circle.setAttribute('r', '40');

const hasPathLength = circle.hasAttribute('pathLength');
console.log(hasPathLength, circle.pathLength.baseVal);

false 0

Größenunabhängige Strich-Animation (Zeichen-Effekt)

// HTML: <svg viewBox="0 0 200 100"><path id="logo" d="M10 80 C 40 10, 65 10, 95 80 S 150 150, 180 80" fill="none" stroke="teal" stroke-width="4"/></svg>
const logo = document.querySelector('#logo');

// Pfadlänge auf 1 normieren – Dash-Werte gelten nun relativ
logo.pathLength.baseVal = 1;
logo.style.strokeDasharray = '1';
logo.style.strokeDashoffset = '1';

logo.animate(
  [{ strokeDashoffset: 1 }, { strokeDashoffset: 0 }],
  { duration: 1500, easing: 'ease-in-out', fill: 'forwards' }
);

console.log(logo.getAttribute('pathLength'));

1

// Wichtig · Fallstricke

Häufiger Irrtum: pathLength gibt nicht die berechnete Länge zurück, auch wenn Kurzbeschreibungen das oft so darstellen. Für die echte Länge nimmt man getTotalLength().
Die Eigenschaft selbst ist schreibgeschützt. Ändern kann man nur pathLength.baseVal, und das schreibt direkt in das Attribut zurück.
Negative Werte sind ein Fehler. Der Wert 0 ist erlaubt, aber dann wird die Dash-Skalierung praktisch unbrauchbar. Ohne Attribut gilt die echte Länge.
pathLength wirkt sich nicht auf getTotalLength() und getPointAtLength() aus. Diese Methoden arbeiten immer mit echten Benutzereinheiten.
Kompatibilität: Mit SVG 2 wurde die Eigenschaft von SVGPathElement nach SVGGeometryElement verschoben. Ältere Browser, besonders ältere Safari-Versionen, werten pathLength bei Grundformen wie <circle> oder <rect> teilweise nicht für Strichmuster aus. Deshalb im Zielbrowser testen.

Siehe auch

SVGGeometryElement SVGGeometryElement.getTotalLength() SVGGeometryElement.getPointAtLength() SVGAnimatedNumber SVGPathElement Element.animate() HTMLTextAreaElement.minLength