GSAP-Bewegungsarchitektur
Verifizierte Basis (2026-11-15)
[email protected]ist die neueste Version auf npm. Ihr Lizenzfeld ist "Standard 'no charge' license" (gsap.com/standard-license): kostenlos für kommerzielle Websites, einschließlich Kundenprojekten. Die einzige verbotene Nutzung ist die Entwicklung von No-Code-Animation-Builder-Tools, die mit Webflow konkurrieren. Alle Plugins werden im öffentlichen Paket ausgeliefert: ScrollTrigger, ScrollSmoother, SplitText, Flip, Observer, Draggable, InertiaPlugin, CustomEase, CustomBounce, CustomWiggle, MorphSVGPlugin, DrawSVGPlugin, MotionPathPlugin, ScrambleTextPlugin, ScrollToPlugin, Physics2D, PhysicsProps, GSDevTools und mehr.@gsap/[email protected]bietetuseGSAP.- Vor einem neuen Projekt erneut prüfen:
npm view gsap version licenseundls node_modules/gsap/*.js. - Verwenden Sie entweder ScrollSmoother oder Lenis, niemals beide. Dieser Studio-Standard verwendet Lenis (
lenis-scrollSkill).
Architektur (Kopieren Sie assets/ in src/motion/)
| Datei | Rolle |
|---|---|
assets/registry.ts | Registriert Plugins einmal, erstellt die benutzerdefinierten Eases des Projekts, setzt Standardwerte, ScrollTrigger.config({ ignoreMobileResize: true }). Alles importiert gsap von hier. |
assets/tokens.ts | Bewegungs-Tokens (Dauern, Eases, Staggers) gespiegelt aus ANIMATION_SPECIFICATION.md + prefersReducedMotion() |
assets/lit.ts | Beispiel einer wiederverwendbaren Textprimitive: SplitText mit aria:'auto', autoSplit und onSplit, der den Tween zurückgibt. Passen Sie das Reveal an die Marke an (lit, masked, slid…). |
assets/useReducedMotion.ts | Live-prefers-reduced-motion-Hook für DOM-Ebenen-Schalter (z. B. statische Schritte anstelle eines Pins rendern) |
assets/examples/*.tsx | Getestete Muster aus der Referenzdemo: gepinnte gescrubbte Sequenz (Method), Flip-Filter (ScheduleIndex), quickTo-gesteuert interaktiv (TheHour), einmalige Reveals (Rooms), Routenübergang-Vorhang (Router) |
Diese Dateien sind die verifizierte Implementierung aus demo/ in diesem Repository, getestet durch seine Playwright-Suite (Bereinigung über Routen hinweg, Reduced Motion, Scroll-Synchronisation).
Regeln, die 90% der GSAP-Fehler in React verhindern
- Jede Animation lebt innerhalb von
useGSAP(() => {...}, { scope: ref }). Der Kontext macht alle Tweens, ScrollTrigger, SplitTexts und matchMedia-Zweige beim Aushängen rückgängig. Animations-Ereignis-Handler verwendencontextSafe. - Erstellen Sie ScrollTrigger niemals im Modulbereich oder in einem einfachen
useEffectohne sie rückgängig zu machen. Rufen SieScrollTrigger.killAll()niemals als Bereinigungsstrategie auf. - Ein
gsap.matchMedia()pro Abschnitt mitmotion/reduce(und Desktop/Mobil-) Bedingungen. Initiale versteckte Zustände werden innerhalb des Bewegungszweigs gesetzt, sodass Benutzer ohne JavaScript und mit Reduced Motion den endgültigen Inhalt sehen. - Strict Mode sicher:
useGSAPbehandelt React 18/19-Doppelaufrufe. Überprüfen Sie mit einem Leck-Check:ScrollTrigger.getAll().lengthkehrt zum Ausgangswert zurück, nachdem Sie weg- und zurücknavigiert sind. - Aktualisierung nach Layout-Änderungen: nachdem Schriftarten geladen sind (
document.fonts.ready.then(() => ScrollTrigger.refresh())), nach dem Filtern von Listen und nachdem Routeninhalte montiert wurden.invalidateOnRefresh: truebei jedem Trigger, dessen Werte aus dem Layout berechnet werden. - Richtig pinnen: einen inneren Wrapper pinnen,
pinSpacingbeibehalten, ihm einemin-height: 100svhgeben, die nicht von Webfonts abhängt, undanticipatePin: 1mit Lenis verwenden. Verwenden Sie einen Pin pro Experience; gestapelte Pins verwirren Benutzer. - Günstige Eigenschaften animieren: transform, opacity, clip-path; CSS-Variablen nur auf kleinen Teilbäumen. Vermeiden Sie width/height/top/left in gescrubbten Timelines und lesen Sie das Layout vor dem Schreiben (GSAP bündelt seine eigenen Schreibvorgänge).
will-changenur während der Animation und nur auf wenigen Ebenen.
Rezepte
references/recipes.md enthält getestete oder dokumentierte Muster für: kinematografische Hero-Sequenz, SplitText-Reveals (Zeichen/Wörter/Zeilen, maskiert), Clip-Path- und Mask-Übergänge, gepinntes Scrub-Storytelling, horizontalen Scroll-Abschnitt (containerAnimation), Parallax-Ebenen, Flip-State-Morphs, Observer-gesteuerte Gestenabschnitte, Draggable + Inertia-Karussells, magnetische Buttons, Cursor-Follower, SVG-Morph/Draw, Bildverzerrung-Übergabe an WebGL, Seitenübergänge und 3D-Scrollen mit einer WebGL-Kamera.
references/react-lifecycle.md behandelt Routenänderungen, Größenänderungen, Inhaltsänderungen und das Debuggen von Lecks.
Checkliste für zielgerichtete Bewegung (bevor Sie animieren)
- Was kommuniziert diese Animation (Hierarchie, Kausalität, Zustand, Markenmaterial)? Wenn nichts, löschen Sie sie.
- Ist es der entscheidende Moment oder sollte es leise bleiben?
- Was zeigt stattdessen Reduced Motion? (Es muss vollständig verständlich bleiben.)
- Was ist der mobile Ausdruck? (Hover-Effekte brauchen eine Touch-Alternative; Pins werden kürzer.)
- Wie viele ScrollTrigger erstellt die Seite? Schreiben Sie das Inventar in die Spezifikation, damit QA es überprüfen kann.