SVGPathElement.getPathSegmentAtLength() — Methode · JavaScript-Referenz

Signatur

SVGPathElement.prototype.getPathSegmentAtLength(distance)

Beschreibung

getPathSegmentAtLength() gehört zur neuen SVG Path Data API (zusammen mit getPathData() und setPathData()). Die Methode bekommt eine Entfernung in Benutzereinheiten, gemessen ab dem Pfadanfang, und gibt das Segment zurück, das an dieser Stelle liegt. Das Ergebnis ist ein Objekt der Form { type, values }, zum Beispiel { type: "C", values: [10, 20, 30, 40, 50, 60] }.

Das ist praktisch, wenn man nicht nur wissen will, wo ein Punkt auf dem Pfad liegt (dafür gibt es getPointAtLength()), sondern auch, welcher Befehl ihn erzeugt. Typische Einsatzfälle sind Pfad-Editoren, das Hervorheben einzelner Segmente beim Überfahren mit der Maus, die Analyse von Animationspfaden oder die Entscheidung, ob eine Stelle auf einer Geraden oder einer Kurve liegt.

Wie lang der ganze Pfad ist, liefert getTotalLength(). Die Entfernung bezieht sich auf die tatsächliche geometrische Länge des Pfads. Das Attribut pathLength spielt dabei keine Rolle. Die Methode ersetzt die alte, inzwischen entfernte Methode getPathSegAtLength(). Diese gab nur einen Index in die veraltete SVGPathSegList zurück.

Parameter

Name	Typ	Default	Beschreibung
$distance Pflicht	number		Entfernung entlang des Pfads in Benutzereinheiten, gemessen ab dem Startpunkt. Sinnvoll sind Werte von `0` bis `getTotalLength()`.

Rückgabewert

Typ

SVGPathSegment | null

Beschreibung

Ein Objekt mit type (Befehlsbuchstabe als String, z. B. "M", "L", "C", "Z") und values (Array der Zahlenparameter). Gibt es kein passendes Segment, etwa bei einem leeren Pfad, ist der Rückgabewert null.

Beispiele

Segment an einer bestimmten Stelle abfragen

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

// Die ersten 100 Einheiten gehören zur ersten Linie, danach folgt die zweite
const seg = path.getPathSegmentAtLength(150);
console.log(seg.type, seg.values);

L [100, 100]

Feature-Erkennung mit Rückfallebene

const describeAt = (path, distance) => {
  const len = path.getTotalLength();
  const d = Math.min(Math.max(distance, 0), len); // Wert selbst begrenzen

  if (typeof path.getPathSegmentAtLength === 'function') {
    const seg = path.getPathSegmentAtLength(d);
    return seg ? `${seg.type}(${seg.values.join(', ')})` : 'kein Segment';
  }
  // Rückfallebene: nur die Koordinate ermitteln
  const { x, y } = path.getPointAtLength(d);
  return `Punkt (${x.toFixed(1)}, ${y.toFixed(1)})`;
};

const path = document.querySelector('path');
console.log(describeAt(path, 42));

z. B. "L(100, 0)" oder als Rückfall "Punkt (42.0, 0.0)"

Segment unter dem Mauszeiger ermitteln (Pfad-Editor)

const path = document.querySelector('#track');
const info = document.querySelector('#info');
const total = path.getTotalLength();

// Die Stelle auf dem Pfad suchen, die dem Mauszeiger am nächsten liegt (grobe Abtastung)
const nearestLength = (px, py, steps = 200) => {
  let best = 0, bestDist = Infinity;
  for (let i = 0; i <= steps; i++) {
    const l = (i / steps) * total;
    const p = path.getPointAtLength(l);
    const dist = (p.x - px) ** 2 + (p.y - py) ** 2;
    if (dist < bestDist) { bestDist = dist; best = l; }
  }
  return best;
};

path.addEventListener('pointermove', (e) => {
  const pt = new DOMPoint(e.clientX, e.clientY)
    .matrixTransform(path.getScreenCTM().inverse());
  const seg = path.getPathSegmentAtLength(nearestLength(pt.x, pt.y));
  if (seg) info.textContent = seg.type === 'C' ? 'Bézierkurve' : `Befehl ${seg.type}`;
});

// Wichtig · Fallstricke

Kompatibilität: Die Methode ist neu und experimentell. Firefox unterstützt sie seit Version 137, in Chromium- und WebKit-Browsern fehlt sie teilweise noch. Deshalb vor der Nutzung immer mit typeof path.getPathSegmentAtLength === 'function' prüfen.
Nicht verwechseln mit der veralteten Methode getPathSegAtLength(). Diese gab nur einen Index zurück und wurde aus den Browsern entfernt.
Negative Werte und Werte größer als getTotalLength() können je nach Implementierung unterschiedlich behandelt werden. Wer ein vorhersagbares Ergebnis braucht, begrenzt die Entfernung selbst auf diesen Bereich.
Das Attribut pathLength wird nicht berücksichtigt. Die Entfernung ist immer die tatsächliche geometrische Länge in Benutzereinheiten, ohne Transformationen.
Das zurückgegebene Segment ist eine Kopie. Wenn man es ändert, bleibt der Pfad unverändert. Zum Ändern getPathData() und setPathData() verwenden.
An der genauen Grenze zwischen zwei Segmenten kann je nach Implementierung das eine oder das andere zurückkommen. Außerdem können type und values relative oder absolute Koordinaten enthalten, abhängig vom ursprünglichen Befehl.
Rufen Sie die Methode nicht bei jedem pointermove-Ereignis für sehr komplexe Pfade auf. Die Längenberechnung von Kurven ist aufwendig. Ergebnisse lieber zwischenspeichern.

Siehe auch

SVGPathElement SVGPathElement.getPathData() SVGPathElement.setPathData() SVGGeometryElement.getTotalLength() SVGGeometryElement.getPointAtLength()