anton-abyzov/vskill

GSAP

HyperFrames-Vertrag

HyperFrames steuert GSAP über seinen gsap-Laufzeitadapter. Erstelle synchron eine pausierte Timeline, registriere sie auf window.__timelines mit der exakten data-composition-id und lasse HyperFrames sie seeken.

<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/gsap.min.js"></script>
<script>
  window.__timelines = window.__timelines || {};
  const tl = gsap.timeline({ paused: true });

  tl.from(".title", { y: 48, opacity: 0, duration: 0.6, ease: "power3.out" }, 0);
  tl.to(".accent", { scaleX: 1, duration: 0.5, ease: "power2.out" }, 0.25);

  window.__timelines["main"] = tl; // Schlüssel muss mit data-composition-id des Kompositions-Roots übereinstimmen
</script>

• Der Registrierungsschlüssel muss mit der data-composition-id des Kompositions-Roots übereinstimmen.
• Rufe tl.play() nicht für renderelevante Bewegungen auf.
• Baue Timelines nicht innerhalb von asynchronem Code, Timern oder Ereignishandlern.
• Halte Schleifen endlich. HyperFrames rendert endliche Videodauern.

Kern-Tween-Methoden

• gsap.to(targets, vars) – animiert vom aktuellen Zustand zu vars. Am häufigsten.
• gsap.from(targets, vars) – animiert von vars zum aktuellen Zustand (Eingänge).
• gsap.fromTo(targets, fromVars, toVars) – expliziter Start- und Endzustand.
• gsap.set(targets, vars) – sofort anwenden (Dauer 0).

Verwende immer camelCase-Eigenschaftsnamen (z.B. backgroundColor, rotationX).

Häufige Variablen (vars)

• duration – Sekunden (Standard 0.5).
• delay – Sekunden vor Start.
• ease – "power1.out" (Standard), "power3.inOut", "back.out(1.7)", "elastic.out(1, 0.3)", "none".
• stagger – Zahl 0.1 oder Objekt: { amount: 0.3, from: "center" }, { each: 0.1, from: "random" }.
• overwrite – false (Standard), true oder "auto".
• repeat – endliche Zahl; niemals -1 in HyperFrames. Berechne Wiederholungen basierend auf der sichtbaren Dauer. yoyo – wechselt die Richtung mit Wiederholung.
• onComplete, onStart, onUpdate – Rückruffunktionen.
• immediateRender – Standard true bei from()/fromTo(). Setze auf false bei späteren Tweens, die dieselbe Eigenschaft+dasselbe Element ansprechen, um Überschreibung zu vermeiden.

Transforms und CSS

Bevorzuge GSAPs Transform-Aliase gegenüber einem rohen transform-String:

GSAP-Eigenschaft	Entsprechung
x, y, z	translateX/Y/Z (px)
xPercent, yPercent	translateX/Y in %
scale, scaleX, scaleY	scale
rotation	rotate (Grad)
rotationX, rotationY	3D-Rotation
skewX, skewY	skew
transformOrigin	transform-origin

• autoAlpha – opacity vorziehen. Bei 0: setzt auch visibility: hidden.
• CSS-Variablen – "--hue": 180.
• svgOrigin (nur SVG) – globaler SVG-Koordinatenraum-Ursprung. Nicht mit transformOrigin kombinieren.
• Richtungsrotation – "360_cw", "-170_short", "90_ccw".
• clearProps – "all" oder kommagetrennt; entfernt Inline-Stile bei Abschluss.
• Relative Werte – "+=20", "-=10", "*=2".

Funktionsbasierte Werte

gsap.to(".item", {
  x: (i, target, targets) => i * 50,
  stagger: 0.1,
});

Easing

Eingebaute Easing-Funktionen: power1–power4, back, bounce, circ, elastic, expo, sine. Jede hat .in, .out, .inOut.

Standardwerte (Defaults)

gsap.defaults({ duration: 0.6, ease: "power2.out" });

Steuerung von Tweens

const tween = gsap.to(".box", { x: 100 });
tween.pause();
tween.play();
tween.reverse();
tween.kill();
tween.progress(0.5);
tween.time(0.2);

gsap.matchMedia() (Responsiv + Barrierefreiheit)

Führt Setup nur aus, wenn eine Media Query zutrifft; macht es automatisch rückgängig, wenn sie nicht mehr zutrifft.

let mm = gsap.matchMedia();
mm.add(
  {
    isDesktop: "(min-width: 800px)",
    reduceMotion: "(prefers-reduced-motion: reduce)",
  },
  (context) => {
    const { isDesktop, reduceMotion } = context.conditions;
    gsap.to(".box", {
      rotation: isDesktop ? 360 : 180,
      duration: reduceMotion ? 0 : 2,
    });
  },
);

---

Timelines

Timeline erstellen

const tl = gsap.timeline({ defaults: { duration: 0.5, ease: "power2.out" } });
tl.to(".a", { x: 100 }).to(".b", { y: 50 }).to(".c", { opacity: 0 });

Positionsparameter

Das dritte Argument steuert die Platzierung:

• Absolut: 1 – bei 1s
• Relativ: "+=0.5" – nach Ende; "-=0.2" – vor Ende
• Label: "intro", "intro+=0.3"
• Ausrichtung: "<" – gleicher Start wie vorheriger; ">" – nach vorherigem Ende; "<0.2" – 0,2s nach Start des vorherigen

tl.to(".a", { x: 100 }, 0);
tl.to(".b", { y: 50 }, "<"); // gleicher Start wie .a
tl.to(".c", { opacity: 0 }, "<0.2"); // 0,2s nach Start von .b

Labels

tl.addLabel("intro", 0);
tl.to(".a", { x: 100 }, "intro");
tl.addLabel("outro", "+=0.5");
tl.play("outro");
tl.tweenFromTo("intro", "outro");

Timeline-Optionen

• paused: true – pausiert erstellen; .play() zum Starten aufrufen.
• repeat, yoyo – auf ganze Timeline anwenden.
• defaults – Variablen, die in jeden Kind-Tween übernommen werden.

Timelines verschachteln

const master = gsap.timeline();
const child = gsap.timeline();
child.to(".a", { x: 100 }).to(".b", { y: 50 });
master.add(child, 0);

Wiedergabesteuerung

tl.play(), tl.pause(), tl.reverse(), tl.restart(), tl.time(2), tl.progress(0.5), tl.kill().

---

Performance

Transform und Opacity bevorzugen

Animationen von x, y, scale, rotation, opacity bleiben auf dem Compositor. Vermeide width, height, top, left, wenn Transforms denselben Effekt erzielen.

will-change

will-change: transform;

Nur auf Elementen, die tatsächlich animiert werden.

gsap.quickTo() für häufige Aktualisierungen

let xTo = gsap.quickTo("#id", "x", { duration: 0.4, ease: "power3" }),
  yTo = gsap.quickTo("#id", "y", { duration: 0.4, ease: "power3" });
container.addEventListener("mousemove", (e) => {
  xTo(e.pageX);
  yTo(e.pageY);
});

Stagger > Viele Tweens

Verwende stagger anstelle separater Tweens mit manuellen Verzögerungen.

Aufräumen

Pausiere oder zerstöre Animationen, die nicht mehr sichtbar sind.

---

Referenzen (werden bei Bedarf geladen)

• references/effects.md – Fertige Effekte: Schreibmaschinentext, Audio-Visualizer. Lesen, wenn vorgefertigte Effektmuster für HyperFrames benötigt werden.

Bewährte Praktiken

• Verwende camelCase-Eigenschaftsnamen; bevorzuge Transform-Aliase und autoAlpha.
• Bevorzuge Timelines gegenüber Verkettung mit delay; verwende den Positionsparameter.
• Füge Labels mit addLabel() für lesbare Ablaufsteuerung hinzu.
• Übergib defaults an den Timeline-Konstruktor.
• Speichere den Rückgabewert von Tween/Timeline, wenn du die Wiedergabe steuerst.

Nicht tun

• Layout-Eigenschaften (width/height/top/left) animieren, wenn Transforms ausreichen.
• Gleichzeitig svgOrigin und transformOrigin auf demselben SVG-Element verwenden.
• Animationen mit delay verketten, wenn eine Timeline sie sequenzieren kann.
• Tweens erstellen, bevor das DOM existiert.
• Aufräumen auslassen – zerstöre Tweens immer, wenn sie nicht mehr benötigt werden.
• Unendliche Wiederholungswerte in HyperFrames-Kompositionen verwenden. Verwende endliche Wiederholungszahlen, die aus der sichtbaren Dauer berechnet werden.

Credits und Referenzen

• HyperFrames-Adapter-Quelle: packages/core/src/runtime/adapters/gsap.ts.
• GSAP-Dokumentation: https://gsap.com/docs/v3/
• GSAP Timeline Pause & Seek Verhalten: https://gsap.com/docs/v3/GSAP/Timeline/pause%28%29/