SVGAnimationElement.beginElementAt() — Methode · JavaScript-Referenz

Signatur

SVGAnimationElement.prototype.beginElementAt(offset)

Beschreibung

beginElementAt() ist eine Methode von SVG-Animationselementen wie <animate>, <animateTransform>, <animateMotion> und <set>. Sie fügt der Liste der Startzeiten der Animation eine neue Anfangsinstanzzeit hinzu. Diese liegt bei der aktuellen Dokumentzeit der SVG-Zeitleiste plus dem übergebenen Versatz in Sekunden.

Die Methode ist das Gegenstück zu beginElement(). beginElement() entspricht beginElementAt(0). Nutze beginElementAt(), wenn eine deklarativ beschriebene Animation durch ein Ereignis ausgelöst werden soll, aber mit Verzögerung starten soll, etwa bei gestaffelten Animationen mehrerer Elemente oder bei einem kurzen Countdown nach einem Klick.

Normalerweise setzt man am Animationselement begin="indefinite". Dann startet die Animation nicht von selbst, sondern nur über das Skript. Ein negativer Versatz ist erlaubt. Die Animation beginnt dann sofort, aber so, als wäre sie schon vor |offset| Sekunden gestartet worden. Sie „springt“ also mitten in ihren Ablauf.

Die Zeitangabe bezieht sich auf die Dokumentzeit des umgebenden <svg>-Elements, nicht auf die Wanduhr. Wurde die Zeitleiste mit svg.pauseAnimations() angehalten, läuft auch der Versatz erst weiter, wenn unpauseAnimations() aufgerufen wird.

Parameter

Name	Typ	Default	Beschreibung
$offset Pflicht	number		Versatz in Sekunden (Gleitkommazahl) relativ zur aktuellen Dokumentzeit. `0` startet sofort, positive Werte verzögern den Start, negative Werte starten die Animation sofort, aber schon ein Stück weit fortgeschritten.

Rückgabewert

Typ

void

Beschreibung

Gibt undefined zurück. Ältere Spezifikationen (SVG 1.1) sahen einen boolean-Rückgabewert vor, heutige Browser liefern keinen Wert.

Beispiele

Animation per Klick mit 1,5 Sekunden Verzögerung starten

const SVG_NS = 'http://www.w3.org/2000/svg';

// SVG mit Kreis und einer Animation erzeugen, die auf ein Skript wartet
const svg = document.createElementNS(SVG_NS, 'svg');
svg.setAttribute('width', '300');
svg.setAttribute('height', '100');

const circle = document.createElementNS(SVG_NS, 'circle');
circle.setAttribute('cx', '20');
circle.setAttribute('cy', '50');
circle.setAttribute('r', '15');
circle.setAttribute('fill', 'tomato');

const anim = document.createElementNS(SVG_NS, 'animate');
anim.setAttribute('attributeName', 'cx');
anim.setAttribute('from', '20');
anim.setAttribute('to', '280');
anim.setAttribute('dur', '2s');
anim.setAttribute('begin', 'indefinite'); // startet nur per Skript
anim.setAttribute('fill', 'freeze');

circle.append(anim);
svg.append(circle);

const button = document.createElement('button');
button.textContent = 'Los (in 1,5 s)';
document.body.append(button, svg);

anim.addEventListener('beginEvent', () => console.log('Animation gestartet'));
button.addEventListener('click', () => {
  anim.beginElementAt(1.5); // Sekunden, nicht Millisekunden!
});

Animation gestartet (ca. 1,5 s nach dem Klick)

Gestaffelte Animation mehrerer Balken

// Vorausgesetzt: <svg id="chart"> mit mehreren <rect>, die jeweils ein
// <animate attributeName="height" begin="indefinite" dur="0.6s" fill="freeze"> enthalten
const animations = document.querySelectorAll('#chart rect > animate');

const playChart = () => {
  animations.forEach((anim, index) => {
    // jeder Balken startet 0,15 s nach dem vorherigen
    anim.beginElementAt(index * 0.15);
  });
};

document.querySelector('#replay').addEventListener('click', playChart);

Negativer Versatz: mitten in der Animation einsteigen

// <animate id="spin" attributeName="transform" ...> wäre für animateTransform üblich
const spin = document.querySelector('#spinner animateTransform');

// dur="4s": Die Drehung beginnt sofort, aber bereits bei 50 % Fortschritt
spin.beginElementAt(-2);

console.log(spin.getStartTime() <= spin.getCurrentTime());

true

// Wichtig · Fallstricke

Einheit: offset wird in Sekunden angegeben, nicht in Millisekunden wie bei setTimeout(). beginElementAt(500) startet also erst nach über 8 Minuten.
begin="indefinite": Ohne diesen Wert kann die Animation zusätzlich durch ihre deklarativen Startzeiten laufen. Das führt leicht zu unerwarteten Doppelstarts. Setze begin="indefinite", wenn nur das Skript die Animation starten soll.
Neustart: Ob ein erneuter Aufruf eine laufende Animation neu startet, hängt vom Attribut restart ab (always, whenNotActive, never). Bei restart="never" bleiben weitere Aufrufe wirkungslos.
Dokumentzeit: Der Versatz bezieht sich auf die SVG-Zeitleiste. Wurde sie mit pauseAnimations() angehalten, startet auch die verzögerte Animation erst nach unpauseAnimations().
Kompatibilität: Alle modernen Browser unterstützen die Methode. Der Internet Explorer und der alte Edge (EdgeHTML) unterstützten SMIL-Animationen nicht. Für komplexere Abläufe ist oft die Web Animations API (Element.animate()) flexibler.

Siehe auch

SVGAnimationElement.beginElement() SVGAnimationElement.endElementAt() SVGAnimationElement.endElement() SVGAnimationElement.getStartTime() SVGAnimationElement.getCurrentTime() SVGAnimationElement SVGSVGElement.pauseAnimations() Element.animate()