SVGAnimationElement — Schnittstelle · JavaScript-Referenz

Signatur

interface SVGAnimationElement extends SVGElement

Beschreibung

SVGAnimationElement ist die gemeinsame Basis für alle deklarativen SVG-Animationen (SMIL). Die konkreten Elemente SVGAnimateElement, SVGSetElement, SVGAnimateMotionElement und SVGAnimateTransformElement erben von diesem Interface, das wiederum von SVGElement erbt. Direkt instanziiert wird es nie – man erhält es über ein vorhandenes Animationselement im DOM oder über document.createElementNS().

Das Interface stellt die Zeitsteuerung per Skript bereit:

Eigenschaften: targetElement (schreibgeschützt, das animierte Element), sowie aus dem Mixin SVGTests requiredExtensions und systemLanguage.
Abfrage-Methoden: getStartTime() (Beginn des aktuellen Intervalls in Sekunden), getCurrentTime() (aktuelle Dokumentzeit), getSimpleDuration() (einfache Dauer, entspricht dur).
Steuer-Methoden: beginElement(), beginElementAt(offset), endElement(), endElementAt(offset).
Ereignisse: beginEvent, endEvent, repeatEvent (bzw. die Properties onbegin, onend, onrepeat).

Typischer Einsatz: Eine Animation mit begin="indefinite" deklarieren und sie dann per JavaScript gezielt auslösen – etwa bei Klick, Hover oder nach dem Laden von Daten. So bleibt die Animation deklarativ im SVG, die Steuerung liegt aber im Skript.

Rückgabewert

Typ

void | number

Beschreibung

Die Steuer-Methoden (beginElement() usw.) liefern undefined. getStartTime(), getCurrentTime() und getSimpleDuration() liefern eine Zeit in Sekunden als number.

Beispiele

Animation per Klick starten (begin="indefinite")

// HTML:
// <svg width="200" height="100">
//   <circle id="ball" cx="20" cy="50" r="15" fill="tomato">
//     <animate id="move" attributeName="cx" from="20" to="180"
//              dur="1s" begin="indefinite" fill="freeze" />
//   </circle>
// </svg>
// <button id="start">Start</button>

const anim = document.getElementById('move');

document.getElementById('start').addEventListener('click', () => {
  anim.beginElement();
  console.log(anim instanceof SVGAnimationElement);
  console.log(anim.targetElement.id);
  console.log(anim.getSimpleDuration());
});

true ball 1

Animation dynamisch erzeugen und verzögert starten

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

const fade = document.createElementNS(SVG_NS, 'animate');
fade.setAttribute('attributeName', 'opacity');
fade.setAttribute('from', '1');
fade.setAttribute('to', '0');
fade.setAttribute('dur', '0.5s');
fade.setAttribute('begin', 'indefinite');
fade.setAttribute('fill', 'freeze');
rect.append(fade);

// Nach 2 Sekunden ausblenden, 0,3 s später abbrechen
fade.beginElementAt(2);
fade.endElementAt(2.3);

Auf Start-, Wiederholungs- und Endereignisse reagieren

const spin = document.querySelector('animateTransform');

const onRepeat = (e) => {
  console.log(`Wiederholung Nr. ${e.detail}`);
};

spin.addEventListener('beginEvent', () => {
  console.log('Start bei', spin.getStartTime().toFixed(2), 's');
});
spin.addEventListener('repeatEvent', onRepeat);

// Alternative über die on-Property
spin.onend = () => {
  console.log('Ende bei', spin.getCurrentTime().toFixed(2), 's');
  spin.removeEventListener('repeatEvent', onRepeat);
};

Start bei 0.00 s Wiederholung Nr. 1 Wiederholung Nr. 2 Ende bei 3.00 s

// Wichtig · Fallstricke

Ausnahmen: getStartTime() wirft einen InvalidStateError, wenn kein aktuelles Intervall existiert (z. B. vor dem ersten Start bei begin="indefinite"). getSimpleDuration() wirft NotSupportedError, wenn die Dauer unbestimmt ist (kein oder indefinite als dur). Aufrufe daher ggf. in try…catch kapseln.
beginElement() funktioniert auch ohne begin="indefinite", fügt dann aber nur einen zusätzlichen Startzeitpunkt hinzu – die Animation startet trotzdem automatisch nach ihrem begin-Wert. Für reine Skriptsteuerung immer begin="indefinite" setzen.
Alle Zeitangaben sind Sekunden (nicht Millisekunden) und beziehen sich auf die Dokumentzeitleiste des umgebenden <svg>. Wird diese mit svg.pauseAnimations() angehalten, bleiben auch die Animationen stehen.
Die Ereignisnamen lauten beginEvent/endEvent/repeatEvent für addEventListener, aber onbegin/onend/onrepeat als Property.
SVGAnimateColorElement (<animateColor>) ist veraltet und in aktuellen Browsern entfernt – stattdessen <animate> verwenden.
Kompatibilität: SMIL-Animationen werden von Chrome, Firefox, Safari und Edge (Chromium) unterstützt; der alte Internet Explorer und das klassische Edge (EdgeHTML) unterstützen sie nicht. Für komplexe Abläufe ist oft die Web Animations API (element.animate()) die flexiblere Alternative.

Siehe auch

Element.animate() SVGAnimateElement SVGAnimateMotionElement SVGAnimateColorElement AnimationEvent