SVGAnimateMotionElement — Schnittstelle · JavaScript-Referenz

Signatur

interface SVGAnimateMotionElement extends SVGAnimationElement

Beschreibung

SVGAnimateMotionElement ist die DOM-Schnittstelle für das SVG-Element <animateMotion>. Damit bewegt sich ein Element deklarativ entlang eines Pfads, z. B. ein Punkt auf einer Kurve, ein Fahrzeug auf einer Route oder ein Ladeindikator auf einer Kreisbahn. Den Pfad legst du über das Attribut path fest, über from/to/by/values oder über ein Kindelement <mpath href="#id">.

Die Schnittstelle bringt keine eigenen Eigenschaften oder Methoden mit. Sie erbt alles von SVGAnimationElement: beginElement(), beginElementAt(), endElement(), endElementAt(), getStartTime(), getCurrentTime(), getSimpleDuration() und targetElement. Dazu kommen die Ereignisse beginEvent, endEvent und repeatEvent.

Wichtige Attribute: path (Pfaddaten wie bei <path d>), rotate (auto, auto-reverse oder ein Winkel), keyPoints zusammen mit keyTimes (Fortschritt entlang des Pfads) sowie calcMode. Hier ist der Standardwert paced, also gleichmäßige Geschwindigkeit. Du erzeugst das Element per JavaScript mit document.createElementNS("http://www.w3.org/2000/svg", "animateMotion") und steuerst es über die geerbten Methoden.

Parameter

Name	Typ	Default	Beschreibung
$path	string		Attribut: Pfaddaten (Syntax wie `d` bei `<path>`), entlang derer sich das Element bewegt. Wird von einem `<mpath>`-Kind überschrieben.
$rotate	"auto" \| "auto-reverse" \| number	0	Attribut: Ausrichtung des Elements. `auto` dreht es in Pfadrichtung mit.
$keyPoints	string		Attribut: Durch Semikolon getrennte Werte zwischen 0 und 1, die den Fortschritt entlang des Pfads angeben. Gehört zu `keyTimes`, erfordert `calcMode="linear"` oder `"spline"`.
$calcMode	"discrete" \| "linear" \| "paced" \| "spline"	paced	Attribut: Interpolationsmodus. Bei `animateMotion` ist der Standardwert `paced`.
$dur / begin / repeatCount	string		Geerbte Zeitsteuerungs-Attribute, z. B. `dur="3s"`, `begin="indefinite"`, `repeatCount="indefinite"`.

Beispiele

Element per JavaScript erzeugen und entlang eines Pfads bewegen

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

const dot = document.createElementNS(SVG_NS, "circle");
dot.setAttribute("r", "5");
dot.setAttribute("fill", "crimson");

const motion = document.createElementNS(SVG_NS, "animateMotion");
motion.setAttribute("path", "M10,50 Q100,0 190,50");
motion.setAttribute("dur", "2s");
motion.setAttribute("repeatCount", "indefinite");
motion.setAttribute("rotate", "auto");

dot.append(motion);
svg.append(dot);
document.body.append(svg);

console.log(motion instanceof SVGAnimateMotionElement);
console.log(motion instanceof SVGAnimationElement);

true true

Animation per Button starten (begin="indefinite")

// HTML:
// <svg viewBox="0 0 200 100">
//   <path id="route" d="M10,80 C60,10 140,10 190,80" fill="none" stroke="#ccc"/>
//   <rect width="10" height="6" x="-5" y="-3" fill="teal">
//     <animateMotion id="car" dur="3s" begin="indefinite" fill="freeze" rotate="auto">
//       <mpath href="#route"/>
//     </animateMotion>
//   </rect>
// </svg>
// <button id="start">Losfahren</button>

const car = document.querySelector("#car");

document.querySelector("#start").addEventListener("click", () => {
  car.beginElement();
});

car.addEventListener("beginEvent", () => console.log("Start"));
car.addEventListener("endEvent", () => console.log("Ziel erreicht"));

Start Ziel erreicht

Zeitangaben und Zielelement abfragen

const motion = document.querySelector("animateMotion");

console.log(motion.targetElement.tagName);   // Element, das bewegt wird
console.log(motion.getSimpleDuration());      // Dauer in Sekunden

setTimeout(() => {
  console.log(motion.getCurrentTime().toFixed(1));
}, 1000);

rect 3 1.0

Ungleichmäßiger Fortschritt mit keyPoints/keyTimes

const motion = document.querySelector("#car");
// Erste Hälfte der Zeit nur 20 % des Wegs, danach schneller
motion.setAttribute("calcMode", "linear");
motion.setAttribute("keyTimes", "0;0.5;1");
motion.setAttribute("keyPoints", "0;0.2;1");
motion.beginElement();

// Wichtig · Fallstricke

Keine eigenen Eigenschaften oder Methoden: Die gesamte Steuerung stammt aus SVGAnimationElement. Attribute wie path oder rotate liest und setzt du über getAttribute() und setAttribute(), denn es gibt keine animierbaren DOM-Eigenschaften dafür.
Namensraum: document.createElement("animateMotion") erzeugt ein unbekanntes HTML-Element und keine SVG-Animation. Verwende immer createElementNS() mit dem SVG-Namensraum.
Priorität der Pfadangaben: <mpath> hat Vorrang vor path, dieses vor values, und values vor from/to/by.
Koordinaten: Die Bewegung wird als zusätzliche Transformation angewendet. Positioniere das animierte Element deshalb um den Ursprung (z. B. cx="0", cy="0"), sonst ist es gegenüber dem Pfad verschoben.
keyPoints wird ignoriert, wenn calcMode="paced" gilt, und das ist der Standardwert.
Kompatibilität: Wird von allen modernen Browsern unterstützt (Chrome, Firefox, Safari, Edge). Der Internet Explorer unterstützt keine SMIL-Animationen. Für komplexere Steuerung eignen sich auch CSS offset-path oder die Web Animations API.
Performance: Viele gleichzeitige SMIL-Animationen können den Hauptthread belasten. Anders als manche CSS-Animationen laufen sie nicht auf dem Compositor.

Siehe auch

SVGAnimateColorElement SVGAnimationElement SVGAnimateElement SVGAnimateTransformElement SVGAnimatedBoolean