SVGAnimationElement.getStartTime() — Methode · JavaScript-Referenz

Signatur

SVGAnimationElement.prototype.getStartTime()

Beschreibung

getStartTime() liefert für ein SMIL-Animationselement (<animate>, <animateTransform>, <animateMotion>, <set>) den Beginn des aktuellen Intervalls als Gleitkommazahl in Sekunden. Der Wert bezieht sich auf die Zeitachse des umgebenden <svg>-Dokuments, also auf dieselbe Zeitbasis wie SVGSVGElement.getCurrentTime().

Die Methode gibt den Wert auch dann zurück, wenn das Intervall zwar schon festgelegt ist, aber noch in der Zukunft liegt. Das passiert zum Beispiel nach beginElementAt(5) oder bei begin="3s", solange die Dokumentzeit unter 3 Sekunden liegt. Gibt es dagegen kein aktuelles Intervall, wirft sie eine DOMException mit dem Namen InvalidStateError. Das ist der Fall bei begin="indefinite" vor dem Start oder nachdem die Animation endgültig beendet ist und kein weiteres Intervall folgt.

Typische Einsatzfälle sind das Berechnen des Fortschritts einer laufenden Animation (zusammen mit getCurrentTime() und getSimpleDuration()), das Abstimmen von JavaScript-Logik auf deklarative SMIL-Zeitsteuerung und die Fehlersuche bei komplexen begin-Bedingungen wie begin="other.end+1s".

Rückgabewert

Typ

number

Beschreibung

Startzeit des aktuellen Intervalls in Sekunden, bezogen auf die Dokumentzeit des SVG-Wurzelelements. Wirft InvalidStateError, wenn kein aktuelles Intervall existiert.

Beispiele

Startzeit einer verzögerten Animation auslesen

const NS = 'http://www.w3.org/2000/svg';
const svg = document.createElementNS(NS, 'svg');
const rect = document.createElementNS(NS, 'rect');
rect.setAttribute('width', '50');
rect.setAttribute('height', '50');

const anim = document.createElementNS(NS, 'animate');
anim.setAttribute('attributeName', 'x');
anim.setAttribute('from', '0');
anim.setAttribute('to', '200');
anim.setAttribute('begin', '2s');
anim.setAttribute('dur', '4s');

rect.append(anim);
svg.append(rect);
document.body.append(svg);

// Das Intervall ist bekannt, obwohl es noch nicht begonnen hat
requestAnimationFrame(() => {
  console.log('Start bei', anim.getStartTime(), 's');
});

Start bei 2 s

Fortschritt einer laufenden Animation in Prozent berechnen

// <svg id="stage"><circle r="10"><animate id="move" attributeName="cx"
//   from="0" to="300" begin="1s" dur="5s" repeatCount="indefinite"/></circle></svg>
const svg = document.getElementById('stage');
const anim = document.getElementById('move');

const progress = () => {
  try {
    const start = anim.getStartTime();
    const dur = anim.getSimpleDuration();
    const elapsed = svg.getCurrentTime() - start;
    if (elapsed < 0) return 0; // Intervall liegt noch in der Zukunft
    return Math.round(((elapsed % dur) / dur) * 100);
  } catch {
    return null; // kein aktuelles Intervall
  }
};

setInterval(() => console.log(`Fortschritt: ${progress()} %`), 1000);

Fortschritt: 0 % Fortschritt: 20 % Fortschritt: 40 % …

InvalidStateError bei begin="indefinite" abfangen

// <svg><rect width="40" height="40"><set id="flash" attributeName="fill"
//   to="red" begin="indefinite" dur="1s"/></rect></svg>
const flash = document.getElementById('flash');

const safeStartTime = (el) => {
  try {
    return el.getStartTime();
  } catch (err) {
    if (err.name === 'InvalidStateError') return null;
    throw err;
  }
};

console.log('Vor dem Start:', safeStartTime(flash));

// Start in 3 Sekunden einplanen
flash.beginElementAt(3);
console.log('Nach beginElementAt(3):', safeStartTime(flash));

Vor dem Start: null Nach beginElementAt(3): 3.0 (bzw. aktuelle Dokumentzeit + 3)

// Wichtig · Fallstricke

Exception statt Rückgabewert: Gibt es kein aktuelles Intervall (etwa bei begin="indefinite" vor dem Start oder nach dem letzten Intervall), wirft die Methode InvalidStateError. Rufe sie deshalb immer in try/catch auf.
Zeitbasis: Der Wert ist Dokumentzeit und keine Wanduhrzeit. Er ist nicht mit performance.now() oder Date.now() vergleichbar. SVGSVGElement.pauseAnimations() und setCurrentTime() wirken sich auf die Dokumentzeit aus.
Wiederholungen: Bei repeatCount bzw. repeatDur bleibt die Startzeit über alle Wiederholungen gleich, denn eine Wiederholung ist kein neues Intervall. Mehrere begin-Werte (z. B. begin="0s;5s") erzeugen dagegen neue Intervalle mit neuer Startzeit.
Zeitpunkt des Aufrufs: Direkt nach dem Einfügen ins DOM ist die Zeitsteuerung eventuell noch nicht aufgelöst. Frage den Wert frühestens nach dem nächsten Frame oder nach dem load-Ereignis ab.
Kompatibilität: SMIL-Animationen und diese Methode werden in Chrome, Edge, Firefox und Safari unterstützt. Für CSS- oder Web-Animations-API-Animationen gilt die Methode nicht, dort übernimmt Animation.startTime diese Rolle.

Siehe auch

SVGAnimationElement SVGAnimationElement.getCurrentTime() SVGAnimationElement.getSimpleDuration() SVGAnimationElement.beginElementAt() SVGSVGElement.getCurrentTime()