SVGPathElement.getPathData() — Methode · JavaScript-Referenz

Signatur

SVGPathElement.prototype.getPathData(options)

Beschreibung

getPathData() gehört zur SVG Path Data API. Die Methode wandelt den Inhalt des d-Attributs eines SVGPathElement in eine strukturierte Liste von Pfadsegmenten um. Jedes Segment ist ein einfaches Objekt mit type (der Befehlsbuchstabe, z. B. "M", "l", "C", "a") und values (ein Array der zugehörigen Zahlen). So muss man den Pfad-String nicht mehr selbst mit regulären Ausdrücken zerlegen.

Ohne Optionen gibt die Methode die Segmente so zurück, wie sie im Pfad stehen, also mit relativen und absoluten Befehlen sowie Kurzformen wie H, V, S, T und Bögen (A). Mit { normalize: true } bekommt man stattdessen eine normalisierte Form: Alle Koordinaten sind absolut, und es kommen nur noch die Befehle M, L, C und Z vor. Quadratische Kurven und Bögen werden dabei in kubische Bézierkurven umgerechnet. Das ist nützlich für Animationen, Morphing, Geometrie-Berechnungen oder den Export in andere Formate.

Typische Anwendungsfälle sind das Auslesen und Verändern von Pfaden in Editoren und Visualisierungen, das Skalieren und Verschieben von Punkten sowie das Umwandeln von Pfaden für Canvas oder WebGL. Zum Zurückschreiben dient die Gegenmethode setPathData().

Parameter

Name	Typ	Default	Beschreibung
$options	Object	{}	Optionales Einstellungsobjekt.
$options.normalize	boolean	false	Bei `true` werden alle Segmente in absolute `M`-, `L`-, `C`- und `Z`-Befehle umgewandelt. Bögen und quadratische Kurven werden dabei zu kubischen Bézierkurven.

Rückgabewert

Typ

Array<{ type: string, values: number[] }>

Beschreibung

Ein Array von Segment-Objekten (SVGPathSegment). type ist der Befehlsbuchstabe, values enthält die Parameter des Befehls. Bei leerem oder ungültigem d-Attribut ist das Array leer bzw. enthält nur die Segmente bis zum ersten Fehler.

Beispiele

Pfadsegmente auslesen

const svgNS = 'http://www.w3.org/2000/svg';
const path = document.createElementNS(svgNS, 'path');
path.setAttribute('d', 'M10 10 h50 v30 Z');

const segments = path.getPathData();
segments.forEach(({ type, values }) => {
  console.log(type, values);
});

M [10, 10] h [50] v [30] Z []

Normalisierte Pfaddaten (nur M, L, C, Z)

const path = document.querySelector('#kurve');
// d="M10 10 h50 q20 20 0 40"
const normalized = path.getPathData({ normalize: true });
console.log(normalized.map((s) => s.type).join(' '));
console.log(normalized[1]);

M L C { type: 'L', values: [60, 10] }

Pfad verschieben und mit setPathData zurückschreiben

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

const verschiebe = (el, dx, dy) => {
  const data = el.getPathData({ normalize: true });
  const moved = data.map(({ type, values }) => ({
    type,
    // Werte paarweise als x/y behandeln – bei M, L, C korrekt
    values: values.map((v, i) => (i % 2 === 0 ? v + dx : v + dy))
  }));
  el.setPathData(moved);
};

verschiebe(path, 20, -5);
console.log(path.getAttribute('d'));

M 30 5 L 80 5 L 80 35 Z (je nach Ausgangspfad)

Feature-Erkennung mit Fallback

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

if (typeof path.getPathData === 'function') {
  console.log(`${path.getPathData().length} Segmente`);
} else {
  // Fallback: Polyfill laden, z. B. path-data-polyfill
  console.warn('Path Data API nicht verfügbar – Polyfill nötig.');
}

4 Segmente

// Wichtig · Fallstricke

Browser-Kompatibilität: Die Path Data API ist lange nur ein Spezifikationsentwurf gewesen und wird erst seit Kurzem unterstützt (Firefox ab Version 137, Chromium in neueren Versionen). Safari unterstützt sie noch nicht. Vorher per Feature-Erkennung prüfen ('getPathData' in SVGPathElement.prototype) und bei Bedarf einen Polyfill wie path-data-polyfill einbinden.

Die zurückgegebenen Objekte sind Kopien. Wer sie ändert, ändert den Pfad nicht. Zum Übernehmen der Änderungen muss man setPathData() aufrufen.
Ohne normalize bleiben relative Befehle (Kleinbuchstaben) erhalten. Deren Werte beziehen sich auf den vorherigen Punkt und lassen sich daher nicht einfach wie absolute Koordinaten verschieben.
Bei Bogensegmenten (A/a) sind nicht alle Werte Koordinaten: Radien, Rotation und die beiden Flags stehen ebenfalls in values. Für Geometrie-Transformationen deshalb besser mit normalize: true arbeiten.
Durch die Normalisierung gehen Informationen verloren. Aus Bögen werden Näherungen mit kubischen Kurven, das Ergebnis ist also nicht exakt dasselbe wie das Original.
Die ältere API pathSegList / SVGPathSeg ist veraltet und in Chrome entfernt worden. Nicht mehr verwenden.

Siehe auch

SVGPathElement SVGPathElement.setPathData() SVGPathElement.getPathSegmentAtLength() SVGGeometryElement.getTotalLength() SVGGeometryElement.getPointAtLength() WindowClient.navigate()