GSAP
Contrat HyperFrames
HyperFrames contrôle GSAP via son adaptateur d'exécution gsap. Créez une timeline en pause de manière synchrone, enregistrez-la sur window.__timelines avec le data-composition-id exact, et laissez HyperFrames la parcourir.
<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; // la clé doit correspondre à data-composition-id sur la racine de la composition
</script>
- La clé du registre doit correspondre au
data-composition-idde la racine de la composition. - N'appelez pas
tl.play()pour les animations critiques pour le rendu. - Ne construisez pas de timelines à l'intérieur de code asynchrone, de temporisateurs ou de gestionnaires d'événements.
- Gardez les boucles finies. HyperFrames rend des durées vidéo finies.
Méthodes de Tween Principales
- gsap.to(targets, vars) — anime de l'état actuel vers
vars. Le plus courant. - gsap.from(targets, vars) — anime de
varsvers l'état actuel (entrées). - gsap.fromTo(targets, fromVars, toVars) — début et fin explicites.
- gsap.set(targets, vars) — applique immédiatement (durée 0).
Utilisez toujours des noms de propriétés en camelCase (par ex. backgroundColor, rotationX).
Propriétés communes
- duration — secondes (par défaut 0.5).
- delay — secondes avant le début.
- ease —
"power1.out"(par défaut),"power3.inOut","back.out(1.7)","elastic.out(1, 0.3)","none". - stagger — nombre
0.1ou objet :{ amount: 0.3, from: "center" },{ each: 0.1, from: "random" }. - overwrite —
false(par défaut),true, ou"auto". - repeat — nombre fini ; jamais
-1dans HyperFrames. Calculez les répétitions à partir de la durée visible. yoyo — alterne la direction avec repeat. - onComplete, onStart, onUpdate — callbacks.
- immediateRender — par défaut
truepour from()/fromTo(). Mettezfalsesur les tweens ultérieurs ciblant la même propriété+élément pour éviter l'écrasement.
Transformations et CSS
Préférez les alias de transformation de GSAP plutôt que la chaîne transform brute :
| Propriété GSAP | Équivalent |
|---|---|
x, y, z | translateX/Y/Z (px) |
xPercent, yPercent | translateX/Y en % |
scale, scaleX, scaleY | scale |
rotation | rotate (degrés) |
rotationX, rotationY | rotation 3D |
skewX, skewY | skew |
transformOrigin | transform-origin |
- autoAlpha — préférez à
opacity. À 0 : définit égalementvisibility: hidden. - Variables CSS —
"--hue": 180. - svgOrigin (SVG uniquement) — origine de l'espace de coordonnées SVG global. Ne combinez pas avec
transformOrigin. - Rotation directionnelle —
"360_cw","-170_short","90_ccw". - clearProps —
"all"ou séparés par des virgules ; supprime les styles en ligne à la fin. - Valeurs relatives —
"+=20","-=10","*=2".
Valeurs Basées sur des Fonctions
gsap.to(".item", {
x: (i, target, targets) => i * 50,
stagger: 0.1,
});
Easing
Eases intégrés : power1–power4, back, bounce, circ, elastic, expo, sine. Chacun a .in, .out, .inOut.
Valeurs par Défaut
gsap.defaults({ duration: 0.6, ease: "power2.out" });
Contrôle des 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() (Responsive + Accessibilité)
Exécute la configuration uniquement lorsqu'une requête média correspond ; se réinitialise automatiquement lorsqu'elle cesse de correspondre.
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
Créer une Timeline
const tl = gsap.timeline({ defaults: { duration: 0.5, ease: "power2.out" } });
tl.to(".a", { x: 100 }).to(".b", { y: 50 }).to(".c", { opacity: 0 });
Paramètre de Position
Le troisième argument contrôle le placement :
- Absolu :
1— à 1s - Relatif :
"+=0.5"— après la fin ;"-=0.2"— avant la fin - Label :
"intro","intro+=0.3" - Alignement :
"<"— même début que le précédent ;">"— après la fin du précédent ;"<0.2"— 0.2s après le début du précédent
tl.to(".a", { x: 100 }, 0);
tl.to(".b", { y: 50 }, "<"); // même début que .a
tl.to(".c", { opacity: 0 }, "<0.2"); // 0.2s après le début de .b
Labels
tl.addLabel("intro", 0);
tl.to(".a", { x: 100 }, "intro");
tl.addLabel("outro", "+=0.5");
tl.play("outro");
tl.tweenFromTo("intro", "outro");
Options de Timeline
- paused: true — crée en pause ; appelez
.play()pour démarrer. - repeat, yoyo — appliquez à toute la timeline.
- defaults — vars fusionnés dans chaque tween enfant.
Imbrication de Timelines
const master = gsap.timeline();
const child = gsap.timeline();
child.to(".a", { x: 100 }).to(".b", { y: 50 });
master.add(child, 0);
Contrôle de la Lecture
tl.play(), tl.pause(), tl.reverse(), tl.restart(), tl.time(2), tl.progress(0.5), tl.kill().
Performances
Préférez Transformation et Opacité
Animer x, y, scale, rotation, opacity reste sur le compositeur. Évitez width, height, top, left lorsque les transformations obtiennent le même effet.
will-change
will-change: transform;
Uniquement sur les éléments qui s'animent réellement.
gsap.quickTo() pour les Mises à Jour Fréquentes
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 > Plusieurs Tweens
Utilisez stagger au lieu de tweens séparés avec des délais manuels.
Nettoyage
Mettez en pause ou tuez les animations hors écran.
Références (chargées à la demande)
- references/effects.md — Effets prêts à l'emploi : texte machine à écrire, visualiseur audio. Lisez-le lorsque vous avez besoin de motifs d'effets prêts à l'emploi pour HyperFrames.
Bonnes Pratiques
- Utilisez des noms de propriétés en camelCase ; préférez les alias de transformation et autoAlpha.
- Préférez les timelines plutôt que l'enchaînement avec delay ; utilisez le paramètre de position.
- Ajoutez des labels avec
addLabel()pour un séquençage lisible. - Passez les defaults dans le constructeur de la timeline.
- Stockez la valeur de retour du tween/timeline lorsque vous contrôlez la lecture.
À Ne Pas Faire
- Animer les propriétés de mise en page (width/height/top/left) lorsque les transformations suffisent.
- Utiliser à la fois svgOrigin et transformOrigin sur le même élément SVG.
- Enchaîner les animations avec delay lorsqu'une timeline peut les séquencer.
- Créer des tweens avant que le DOM n'existe.
- Sauter le nettoyage — tuez toujours les tweens lorsqu'ils ne sont plus nécessaires.
- Utiliser des valeurs de répétition infinies dans les compositions HyperFrames. Utilisez des comptes de répétition finis calculés à partir de la durée visible.
Crédits et Références
- Source de l'adaptateur HyperFrames :
packages/core/src/runtime/adapters/gsap.ts. - Documentation GSAP : https://gsap.com/docs/v3/
- Comportement de pause et de recherche de timeline GSAP : https://gsap.com/docs/v3/GSAP/Timeline/pause%28%29/