SVGGeometryElement — Schnittstelle · JavaScript-Referenz

Signatur

interface SVGGeometryElement extends SVGGraphicsElement

Beschreibung

SVGGeometryElement ist die gemeinsame Basis aller SVG-Grundformen: <path>, <rect>, <circle>, <ellipse>, <line>, <polyline> und <polygon>. Jede dieser Formen hat einen äquivalenten Pfad, also eine Beschreibung ihrer Kontur als Pfad. Das Interface erbt von SVGGraphicsElement (und damit u. a. getBBox() und getCTM()) und wird selbst nie direkt instanziiert. Es tritt immer als Prototyp einer konkreten Form auf.

Wichtige Mitglieder:

pathLength (SVGAnimatedNumber): spiegelt das Attribut pathLength wider. Damit legt der Autor eine eigene Gesamtlänge fest, nach der Längenangaben wie stroke-dasharray skaliert werden.
getTotalLength(): liefert die berechnete Länge des Pfads in Benutzereinheiten.
getPointAtLength(distance): liefert den Punkt (DOMPoint), der die angegebene Strecke vom Pfadanfang entfernt liegt.
isPointInFill(point) / isPointInStroke(point): prüfen, ob ein Punkt im lokalen Koordinatensystem der Form innerhalb der Füllung bzw. auf der Kontur liegt.

Typische Einsatzfälle sind Linien-Zeichenanimationen mit stroke-dasharray/stroke-dashoffset, Objekte, die sich entlang eines Pfads bewegen, genaue Treffertests (Hit-Testing) für unregelmäßige Formen sowie Diagramme und Datenvisualisierungen, bei denen Punkte auf Kurven gebraucht werden.

Rückgabewert

Typ

SVGGeometryElement

Beschreibung

Kein Konstruktor. Instanzen erhält man über document.createElementNS('http://www.w3.org/2000/svg', …) oder DOM-Abfragen. Die Methoden liefern number (getTotalLength), DOMPoint (getPointAtLength) bzw. boolean (isPointInFill/isPointInStroke).

Beispiele

Form erzeugen und Länge bestimmen

const SVG_NS = 'http://www.w3.org/2000/svg';
const svg = document.createElementNS(SVG_NS, 'svg');
svg.setAttribute('viewBox', '0 0 200 200');

const circle = document.createElementNS(SVG_NS, 'circle');
circle.setAttribute('cx', '100');
circle.setAttribute('cy', '100');
circle.setAttribute('r', '50');
svg.append(circle);
document.body.append(svg);

console.log(circle instanceof SVGGeometryElement);
console.log(circle.getTotalLength().toFixed(2)); // 2 * PI * 50

true 314.16

Linie „zeichnen“ lassen (Stroke-Animation)

// <path id="signatur" d="M10 80 C 40 10, 65 10, 95 80 S 150 150, 180 80" fill="none" stroke="black"/>
const path = document.querySelector('#signatur');
const length = path.getTotalLength();

path.style.strokeDasharray = length;
path.style.strokeDashoffset = length;

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

Objekt entlang eines Pfads bewegen

const path = document.querySelector('#bahn');
const dot = document.querySelector('#punkt'); // ein <circle>
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);

Präziser Treffertest mit isPointInFill

const svg = document.querySelector('svg');
const shape = document.querySelector('#stern'); // <polygon>

svg.addEventListener('pointermove', (event) => {
  // Bildschirmkoordinaten ins lokale System der Form umrechnen
  const pt = new DOMPoint(event.clientX, event.clientY)
    .matrixTransform(shape.getScreenCTM().inverse());

  const inFill = shape.isPointInFill(pt);
  const onStroke = shape.isPointInStroke(pt);
  shape.classList.toggle('hover', inFill || onStroke);
});

// Wichtig · Fallstricke

Namensraum beachten: document.createElement('circle') erzeugt ein HTMLUnknownElement und kein SVG-Element. Immer createElementNS('http://www.w3.org/2000/svg', …) verwenden.
pathLength beeinflusst die Methoden nicht: getTotalLength() und getPointAtLength() arbeiten immer mit der tatsächlich berechneten Länge, auch wenn ein pathLength-Attribut gesetzt ist. Das Attribut skaliert nur Stroke-Dash-Werte und Textpfad-Offsets.
Koordinatensystem: isPointInFill()/isPointInStroke() erwarten lokale Koordinaten. Mausposition deshalb mit getScreenCTM().inverse() umrechnen. isPointInStroke() berücksichtigt stroke-width, stroke-linecap usw.
Rendering-Zustand: Bei nicht gerenderten Elementen (z. B. ohne Dokumentanbindung oder mit display: none) können Browser eine Ausnahme werfen oder 0 liefern. Messungen am besten erst nach dem Einfügen ins DOM vornehmen.
Kompatibilität: getTotalLength()/getPointAtLength() gab es früher nur an SVGPathElement. Auf alle Grundformen verallgemeinert wurden sie mit SVG 2. isPointInFill/isPointInStroke werden erst von neueren Versionen unterstützt (Chrome 66+, Firefox 69+, Safari 14+). Den Internet Explorer gibt es nicht mehr. Wer ihn noch unterstützen muss, braucht einen Fallback.
Performance: getPointAtLength() ist bei komplexen Pfaden verhältnismäßig teuer. Werte für viele Frames besser einmal vorab berechnen und zwischenspeichern.

Siehe auch

SVGFEMergeElement SVGAnimateElement SVGFEBlendElement SVGFEFuncRElement SVGFEImageElement