GSAP
HyperFrames-Vertrag
HyperFrames steuert GSAP über seinen gsap-Laufzeitadapter. Erstellen Sie synchron eine pausierte Timeline, registrieren Sie sie mit der exakten data-composition-id auf window.__timelines und lassen Sie HyperFrames sie abspielen.
<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 auf dem Kompositionswurzelelement übereinstimmen
</script>
- Der Registrierungsschlüssel muss mit der
data-composition-iddes Kompositionswurzelelements übereinstimmen. - Rufen Sie
tl.play()nicht für rendernotwendige Bewegungen auf. - Erstellen Sie Timelines nicht innerhalb von asynchronem Code, Timern oder Event-Handlern.
- Halten Sie Schleifen endlich. HyperFrames rendert endliche Videodauern.
Kern-Tween-Methoden
- gsap.to(targets, vars) — Animiert vom aktuellen Zustand zu
vars. Am häufigsten verwendet. - gsap.from(targets, vars) — Animiert von
varszum aktuellen Zustand (Eingänge). - gsap.fromTo(targets, fromVars, toVars) — Expliziter Start- und Endpunkt.
- gsap.set(targets, vars) — Wird sofort angewendet (Dauer 0).
Verwenden Sie immer camelCase-Eigenschaftsnamen (z.B. backgroundColor, rotationX).
Häufige 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.1oder Objekt:{ amount: 0.3, from: "center" },{ each: 0.1, from: "random" }. - overwrite —
false(Standard),trueoder"auto". - repeat — Endliche Zahl; niemals
-1in HyperFrames. Berechnen Sie Wiederholungen basierend auf der sichtbaren Dauer. yoyo — Wechselt die Richtung bei Wiederholung. - onComplete, onStart, onUpdate — Rückruffunktionen.
- immediateRender — Standard
truebei from()/fromTo(). Setzen Siefalsebei späteren Tweens, die dieselbe Eigenschaft und dasselbe Element anvisieren, um Überschreiben zu vermeiden.
Transforms und CSS
Bevorzugen Sie GSAPs Transform-Aliasnamen gegenüber rohem transform-String:
| GSAP-Eigenschaft | Äquivalent |
|---|---|
x, y, z | translateX/Y/Z (px) |
xPercent, yPercent | translateX/Y in % |
scale, scaleX, scaleY | scale |
rotation | rotate (Grad) |
rotationX, rotationY | 3D-Rotate |
skewX, skewY | skew |
transformOrigin | transform-origin |
- autoAlpha — Bevorzugen Sie es gegenüber
opacity. Bei 0: Setzt ebenfallsvisibility: hidden. - CSS-Variablen —
"--hue": 180. - svgOrigin (nur SVG) — Globaler SVG-Koordinatenraum-Ursprung. Nicht mit
transformOriginkombinieren. - 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.
Defaults
gsap.defaults({ duration: 0.6, ease: "power2.out" });
Tweens steuern
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; wird automatisch rückgängig gemacht, 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
Eine 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 vorherige;">"— nach dem Ende der vorherigen;"<0.2"— 0.2s nach Start der 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 — Erstellt pausiert; rufen Sie
.play()auf, um zu starten. - repeat, yoyo — Auf die gesamte Timeline anwendbar.
- defaults — Vars werden in jeden untergeordneten Tween eingemischt.
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
Das Animieren von x, y, scale, rotation, opacity bleibt auf dem Compositor. Vermeiden Sie 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 statt vieler Tweens
Verwenden Sie stagger anstelle separater Tweens mit manuellen Verzögerungen.
Bereinigung
Pausieren oder beenden Sie Animationen, die nicht mehr sichtbar sind.
Referenzen (bei Bedarf geladen)
- references/effects.md — Fertige Effekte: Schreibmaschinentext, Audio-Visualizer. Lesen Sie dies, wenn Sie gebrauchsfertige Effektmuster für HyperFrames benötigen.
Best Practices
- Verwenden Sie camelCase-Eigenschaftsnamen; bevorzugen Sie Transform-Aliasnamen und autoAlpha.
- Bevorzugen Sie Timelines gegenüber Verkettungen mit delay; verwenden Sie den Positionsparameter.
- Fügen Sie Labels mit
addLabel()für lesbare Sequenzen hinzu. - Übergeben Sie defaults an den Timeline-Konstruktor.
- Speichern Sie den Rückgabewert von Tween/Timeline, wenn Sie die Wiedergabe steuern möchten.
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.
- Keine Bereinigung durchführen — beenden Sie Tweens immer, wenn sie nicht mehr benötigt werden.
- Unendliche Wiederholungswerte in HyperFrames-Kompositionen verwenden. Verwenden Sie endliche Wiederholungszahlen, die aus der sichtbaren Dauer berechnet werden.
Quellen und Referenzen
- HyperFrames-Adapterquelle:
packages/core/src/runtime/adapters/gsap.ts. - GSAP-Dokumentation: https://gsap.com/docs/v3/
- GSAP Timeline Pause- und Seek-Verhalten: https://gsap.com/docs/v3/GSAP/Timeline/pause%28%29/