SVGGeometryElement.getPointAtLength() — Methode · JavaScript-Referenz

Signatur

SVGGeometryElement.prototype.getPointAtLength(distance)

Beschreibung

getPointAtLength() berechnet die Koordinaten des Punktes, der sich in der angegebenen Entfernung vom Anfang der Kontur eines SVG-Geometrie-Elements befindet. Zu diesen Elementen gehören <path>, <circle>, <ellipse>, <line>, <polyline>, <polygon> und <rect>. Die Entfernung wird entlang der Kurve gemessen, nicht als Luftlinie.

Typische Einsatzgebiete sind Animationen, bei denen ein Objekt einem Pfad folgt, das Platzieren von Markierungen oder Beschriftungen in gleichmäßigen Abständen, das Abtasten einer Kurve in einzelne Punkte (etwa für Canvas, Kollisionsprüfung oder Morphing) sowie Fortschrittsanzeigen entlang einer beliebigen Form. In Kombination mit getTotalLength() lässt sich ein relativer Fortschritt von 0 bis 1 in eine Position umrechnen.

Die zurückgegebenen Koordinaten liegen im lokalen Benutzerkoordinatensystem des Elements. Ein transform-Attribut am Element oder an Elterngruppen wird also nicht berücksichtigt. Für Bildschirmkoordinaten muss der Punkt mit getScreenCTM() bzw. getCTM() umgerechnet werden. Hat das Element ein pathLength-Attribut, wird distance auf diese Autorenlänge skaliert.

Parameter

Name	Typ	Default	Beschreibung
$distance Pflicht	number		Entfernung entlang der Kontur vom Startpunkt, in Benutzereinheiten (bzw. skaliert auf `pathLength`, falls gesetzt). Werte kleiner als 0 werden auf 0 begrenzt, Werte über der Gesamtlänge auf die Gesamtlänge.

Rückgabewert

Typ

DOMPoint

Beschreibung

Ein DOMPoint (in älteren Implementierungen SVGPoint) mit den Eigenschaften x und y im lokalen Koordinatensystem des Elements.

Beispiele

Punkt in der Mitte eines Pfades ermitteln

const path = document.querySelector('#route');
// <path id="route" d="M 10 10 L 110 10" />
const total = path.getTotalLength();
const mid = path.getPointAtLength(total / 2);
console.log(total, mid.x, mid.y);

100 60 10

Objekt entlang eines Pfades animieren

const path = document.querySelector('#track');
const dot = document.querySelector('#dot'); // <circle r="5">
const total = path.getTotalLength();
const duration = 3000;
let start;

const step = (time) => {
  start ??= time;
  const progress = ((time - start) % duration) / duration;
  const { x, y } = path.getPointAtLength(progress * total);
  dot.setAttribute('cx', x);
  dot.setAttribute('cy', y);
  requestAnimationFrame(step);
};

requestAnimationFrame(step);

Kurve in gleichmäßige Punkte zerlegen

const samplePath = (el, count) => {
  const total = el.getTotalLength();
  return Array.from({ length: count }, (_, i) => {
    const p = el.getPointAtLength((i / (count - 1)) * total);
    return { x: +p.x.toFixed(2), y: +p.y.toFixed(2) };
  });
};

const circle = document.querySelector('circle'); // cx=50 cy=50 r=40
console.log(samplePath(circle, 3));

[{x: 90, y: 50}, {x: 10, y: 50}, {x: 90, y: 50}]

Punkt in Bildschirmkoordinaten umrechnen

const path = document.querySelector('#route');
const local = path.getPointAtLength(50);
const screen = local.matrixTransform(path.getScreenCTM());
console.log(`Bildschirm: ${screen.x}px / ${screen.y}px`);

Bildschirm: 268px / 142px

// Wichtig · Fallstricke

Lokale Koordinaten: Transformationen (transform, viewBox, CSS-Transforms) fließen nicht ein. Mit getScreenCTM() und DOMPoint.matrixTransform() umrechnen.
Nur für gerenderte Elemente zuverlässig: Elemente, die nicht im DOM hängen, sich in display: none befinden oder einen leeren d-Wert haben, können je nach Browser einen Fehler werfen oder (0, 0) liefern. Ein leerer Pfad kann einen InvalidStateError auslösen.
Performance: Jeder Aufruf misst die Kurve neu, was bei komplexen Pfaden teuer ist. getTotalLength() einmal zwischenspeichern und Abtastpunkte nicht in jedem Frame neu erzeugen, wenn sich die Geometrie nicht ändert.
Kompatibilität: Ursprünglich gab es die Methode nur auf SVGPathElement. Auf anderen Formen (circle, rect …) steht sie in älteren Browsern wie Safari < 13 oder dem alten Edge teils nicht zur Verfügung. Der Startpunkt und die Umlaufrichtung von Grundformen sind im SVG-2-Standard festgelegt (z. B. beginnt ein Kreis bei 3 Uhr und läuft im Uhrzeigersinn). Ältere Engines weichen davon teilweise ab.
Der Rückgabetyp war früher SVGPoint. Heute ist es DOMPoint, die Eigenschaften x/y sind dieselben.

Siehe auch

SVGGeometryElement SVGGeometryElement.getTotalLength() SVGGeometryElement.isPointInFill() SVGGeometryElement.isPointInStroke() SVGGraphicsElement.getScreenCTM() SVGPathElement