SVGMPathElement — Schnittstelle · JavaScript-Referenz

Signatur

interface SVGMPathElement extends SVGElement

Beschreibung

SVGMPathElement ist die DOM-Schnittstelle für das Element <mpath>. Es steht nur als Kind eines <animateMotion>-Elements. Über sein href-Attribut verweist es auf ein vorhandenes <path>-Element. Die Animation bewegt das Zielelement dann entlang dieser Pfadgeometrie. So kann ein einzelner Pfad gleichzeitig sichtbar sein und als Bewegungsbahn dienen. Außerdem können sich mehrere Animationen denselben Pfad teilen.

Die Schnittstelle erbt alle Eigenschaften und Methoden von SVGElement. Aus dem Mixin SVGURIReference kommt die Eigenschaft href dazu. Sie ist ein SVGAnimatedString: href.baseVal enthält den im Markup gesetzten Wert und lässt sich beschreiben. href.animVal ist der aktuelle, nur lesbare Wert.

Die Schnittstelle brauchst du, wenn du Bewegungsanimationen per JavaScript erzeugst oder zur Laufzeit auf einen anderen Pfad umschaltest. Beispiele sind Fahrzeuge auf einer Route, Punkte entlang eines Diagramms oder Ladeanimationen. Hat <animateMotion> ein <mpath>-Kind, hat dieses Vorrang vor den Attributen path, values, from und to.

Parameter

Name	Typ	Default	Beschreibung
$href Pflicht	SVGAnimatedString		Eigenschaft, nur lesbar (die Eigenschaft selbst). Bildet das Attribut `href` bzw. `xlink:href` ab. Du änderst es über `href.baseVal`, z. B. auf `'#route'`.

Rückgabewert

Typ

SVGMPathElement

Beschreibung

Das bekommst du von document.createElementNS('http://www.w3.org/2000/svg', 'mpath') oder von DOM-Abfragen wie querySelector('mpath').

Beispiele

Bewegungsanimation per JavaScript aufbauen

const SVG_NS = 'http://www.w3.org/2000/svg';
const svg = document.querySelector('svg');

// Sichtbarer Pfad, der zugleich die Bewegungsbahn ist
const path = document.createElementNS(SVG_NS, 'path');
path.id = 'route';
path.setAttribute('d', 'M20,100 C80,10 180,190 280,100');
path.setAttribute('fill', 'none');
path.setAttribute('stroke', '#999');
svg.append(path);

// Kreis, der sich bewegen soll
const dot = document.createElementNS(SVG_NS, 'circle');
dot.setAttribute('r', '6');
dot.setAttribute('fill', 'crimson');

const motion = document.createElementNS(SVG_NS, 'animateMotion');
motion.setAttribute('dur', '3s');
motion.setAttribute('repeatCount', 'indefinite');
motion.setAttribute('rotate', 'auto');

const mpath = document.createElementNS(SVG_NS, 'mpath');
mpath.href.baseVal = '#route';

motion.append(mpath);
dot.append(motion);
svg.append(dot);

console.log(mpath instanceof SVGMPathElement, mpath.href.baseVal);

true "#route"

Route zur Laufzeit umschalten

// Markup:
// <svg viewBox="0 0 300 200">
//   <path id="a" d="M10,10 L290,190" fill="none" stroke="#ccc"/>
//   <path id="b" d="M10,190 L290,10" fill="none" stroke="#ccc"/>
//   <circle r="5"><animateMotion dur="2s" repeatCount="indefinite">
//     <mpath href="#a"/></animateMotion></circle>
//   <button id="toggle">Route wechseln</button>
// </svg>

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

document.querySelector('#toggle').addEventListener('click', () => {
  const next = mpath.href.baseVal === '#a' ? '#b' : '#a';
  mpath.href.baseVal = next;
  console.log('Aktive Route:', mpath.href.animVal);
});

Aktive Route: #b

Referenzierten Pfad auslesen und vermessen

const mpath = document.querySelector('animateMotion > mpath');
const id = mpath.href.baseVal.replace(/^#/, '');
const target = document.getElementById(id);

if (target instanceof SVGPathElement) {
  console.log(`Pfadlänge: ${target.getTotalLength().toFixed(1)}`);
} else {
  console.warn('mpath verweist auf kein gültiges <path>-Element');
}

Pfadlänge: 312.4

// Wichtig · Fallstricke

Namensraum: Erzeuge das Element immer mit document.createElementNS('http://www.w3.org/2000/svg', 'mpath'). createElement('mpath') erzeugt nur ein unbekanntes HTML-Element ohne Funktion.
href und xlink:href: Moderne Browser verstehen das einfache href. Ältere Safari-Versionen (vor 12) brauchen xlink:href, gesetzt mit setAttributeNS('http://www.w3.org/1999/xlink', 'xlink:href', '#id'). Wenn beide Attribute vorhanden sind, gewinnt href.
Zielelement: Das Ziel muss ein <path> oder ab SVG 2 eine andere Grundform (SVGGeometryElement) sein. Ist der Verweis ungültig oder fehlt er, wird die Bewegungsanimation ignoriert. Ein Fehler wird dabei nicht gemeldet.
Vorrang: Ein <mpath>-Kind überschreibt die Attribute path, values, from und to am <animateMotion>.
Kompatibilität: SMIL-Animationen einschließlich <mpath> funktionieren in Chrome, Edge, Firefox und Safari. In Internet Explorer funktionieren sie nie. Als Alternative in CSS eignen sich offset-path und offset-distance.

Siehe auch

SVGPathElement SVGMaskElement SVGAElement SVGClipPathElement SVGImageElement