SVGAnimationElement.getSimpleDuration() — Methode · JavaScript-Referenz

Signatur

SVGAnimationElement.prototype.getSimpleDuration()

Beschreibung

getSimpleDuration() ist eine Methode aller SVG-Animationselemente, die von SVGAnimationElement erben, also <animate>, <animateTransform>, <animateMotion> und <set>. Sie liefert die einfache Dauer (englisch simple duration) der Animation in Sekunden. Das ist die Dauer eines einzelnen Durchlaufs, wie sie im Attribut dur festgelegt ist.

Wichtig ist der Unterschied zur aktiven Dauer: Attribute wie repeatCount, repeatDur, min, max oder end haben keinen Einfluss auf den Rückgabewert. Bei dur="2s" repeatCount="3" gibt die Methode also 2 zurück und nicht 6.

Nützlich ist die Methode, wenn du per Skript mit einer deklarativen SMIL-Animation arbeitest. Du kannst damit zum Beispiel den Fortschritt innerhalb des aktuellen Durchlaufs berechnen (zusammen mit getStartTime() und getCurrentTime()), eine Fortschrittsanzeige synchron halten oder JavaScript-Aktionen auf die Länge einer SVG-Animation abstimmen, ohne das Attribut dur selbst auszuwerten (etwa "1.5s", "1500ms" oder "00:01.5").

Rückgabewert

Typ

number

Beschreibung

Die einfache Dauer der Animation in Sekunden als Gleitkommazahl (z. B. 1.5 für dur="1500ms"). Wenn keine einfache Dauer bestimmt werden kann, wird ein DOMException vom Typ NotSupportedError ausgelöst.

Beispiele

Einfache Dauer einer Animation auslesen

// <svg><circle r="10" cx="20" cy="20">
//   <animate id="puls" attributeName="r" from="10" to="20"
//            dur="1500ms" repeatCount="3" />
// </circle></svg>

const anim = document.getElementById('puls');
const dauer = anim.getSimpleDuration();

// repeatCount wird NICHT berücksichtigt
console.log(`Ein Durchlauf dauert ${dauer} s`);

Ein Durchlauf dauert 1.5 s

Unbestimmte Dauer sicher abfangen

// <animate id="endlos" attributeName="opacity" from="0" to="1"
//          dur="indefinite" />

const ermittleDauer = (animElement) => {
  try {
    return animElement.getSimpleDuration();
  } catch (err) {
    if (err.name === 'NotSupportedError') {
      return Infinity; // keine bestimmte einfache Dauer
    }
    throw err;
  }
};

const anim = document.getElementById('endlos');
console.log(ermittleDauer(anim));

Infinity

Fortschritt des aktuellen Durchlaufs berechnen

// <animate id="lauf" attributeName="cx" from="0" to="300"
//          dur="4s" repeatCount="indefinite" />
// <progress id="balken" max="1"></progress>

const anim = document.getElementById('lauf');
const balken = document.getElementById('balken');

const aktualisiere = () => {
  try {
    const start = anim.getStartTime();      // Beginn des aktuellen Intervalls
    const jetzt = anim.getCurrentTime();    // aktuelle Dokumentzeit
    const dauer = anim.getSimpleDuration(); // 4
    const fortschritt = ((jetzt - start) % dauer) / dauer;
    balken.value = fortschritt;
  } catch {
    // Animation noch nicht gestartet oder Dauer unbestimmt
    balken.value = 0;
  }
  requestAnimationFrame(aktualisiere);
};

requestAnimationFrame(aktualisiere);

// Wichtig · Fallstricke

Ausnahme bei unbestimmter Dauer: Fehlt das Attribut dur, ist es ungültig oder steht auf "indefinite", gibt es keine bestimmte einfache Dauer. Dann löst die Methode einen NotSupportedError aus. Setze den Aufruf daher in try…catch, wenn dur nicht sicher gesetzt ist.
Nur ein Durchlauf: repeatCount, repeatDur, end, min und max werden ignoriert. Die gesamte aktive Dauer musst du selbst berechnen.
Einheit ist immer Sekunden, auch wenn dur in Millisekunden oder im Uhrzeitformat angegeben ist.
Nur für SMIL-Animationen: Für CSS-Animationen und die Web Animations API ist die Methode nicht gedacht. Dort nutzt du Animation.effect.getTiming().duration.
Kompatibilität: Wird von Chrome, Edge, Firefox und Safari unterstützt. Das genaue Verhalten bei Randfällen, zum Beispiel direkt nach einer Änderung von dur per Skript, kann sich zwischen den Browsern leicht unterscheiden. Am besten liest du den Wert nach der Änderung neu aus.

Siehe auch

SVGAnimationElement SVGAnimationElement.getStartTime() SVGAnimationElement.getCurrentTime() SVGAnimationElement.beginElement() SVGAnimationElement.endElement() SVGSVGElement.getCurrentTime()