GSAP Timeline
Quand utiliser cette compétence
À appliquer lors de la création d'animations multi-étapes, de la coordination de plusieurs tweens en séquence ou en parallèle, ou lorsque l'utilisateur pose des questions sur les timelines, le séquencement, ou les animations de type image clé dans GSAP.
Compétences associées : Pour les tweens simples et les easing, utiliser gsap-core ; pour les timelines pilotées par le défilement, utiliser gsap-scrolltrigger ; pour React, utiliser gsap-react.
Création d'une timeline
const tl = gsap.timeline();
tl.to(".a", { x: 100, duration: 1 })
.to(".b", { y: 50, duration: 0.5 })
.to(".c", { opacity: 0, duration: 0.3 });
Par défaut, les tweens sont ajoutés les uns après les autres. Utilisez le paramètre de position pour placer les tweens à des moments spécifiques ou par rapport à d'autres tweens.
Paramètre de position
Troisième argument (ou propriété position dans les options) contrôle le placement :
- Absolu :
1— commence à 1 seconde. - Relatif (par défaut) :
"+=0.5"— 0,5 s après la fin ;"-=0.2"— 0,2 s avant la fin. - Label :
"labelName"— à ce label ;"labelName+=0.3"— 0,3 s après le label. - Placement :
"<"— commence au début de l'animation ajoutée récemment ;">"— commence à la fin de l'animation ajoutée récemment (par défaut) ;"<0.2"— 0,2 s après le début de l'animation ajoutée récemment.
Exemples :
tl.to(".a", { x: 100 }, 0); // à 0
tl.to(".b", { y: 50 }, "+=0.5"); // 0,5 s après la dernière fin
tl.to(".c", { opacity: 0 }, "<"); // même début que le précédent
tl.to(".d", { scale: 2 }, "<0.2"); // 0,2 s après le début précédent
Valeurs par défaut de la timeline
Passez des valeurs par défaut dans le constructeur de la timeline pour que tous les tweens enfants les héritent :
const tl = gsap.timeline({ defaults: { duration: 0.5, ease: "power2.out" } });
tl.to(".a", { x: 100 }).to(".b", { y: 50 }); // les deux utilisent 0,5 s et power2.out
Options de la timeline (constructeur)
- paused: true — crée en pause ; appeler
.play()pour démarrer. - repeat, yoyo — identique aux tweens ; s'applique à toute la timeline.
- onComplete, onStart, onUpdate — callbacks au niveau de la timeline.
- defaults — options fusionnées dans chaque tween enfant.
Labels
Ajoutez et utilisez des labels pour un séquencement lisible et maintenable :
tl.addLabel("intro", 0);
tl.to(".a", { x: 100 }, "intro");
tl.addLabel("outro", "+=0.5");
tl.to(".b", { opacity: 0 }, "outro");
tl.play("outro"); // démarre à partir de "outro"
tl.tweenFromTo("intro", "outro"); // met la timeline en pause et retourne un nouveau Tween qui anime la tête de lecture de la timeline de intro à outro sans easing.
Imbrication de timelines
Les timelines peuvent contenir d'autres timelines.
const master = gsap.timeline();
const child = gsap.timeline();
child.to(".a", { x: 100 }).to(".b", { y: 50 });
master.add(child, 0);
master.to(".c", { opacity: 0 }, "+=0.2");
Contrôle de la lecture
- tl.play() / tl.pause()
- tl.reverse() / tl.progress(1) puis tl.reverse()
- tl.restart() — depuis le début.
- tl.time(2) — aller à 2 secondes.
- tl.progress(0.5) — aller à 50 %.
- tl.kill() — tuer la timeline et (par défaut) ses enfants.
Bonnes pratiques officielles GSAP
- ✅ Privilégier les timelines pour le séquencement
- ✅ Utiliser le paramètre de position (troisième argument) pour placer les tweens à des moments spécifiques ou par rapport à des labels.
- ✅ Ajouter des labels avec
addLabel()pour un séquencement lisible et maintenable. - ✅ Passer defaults dans le constructeur de la timeline pour que les tweens enfants héritent de la durée, de l'easing, etc.
- ✅ Mettre ScrollTrigger sur la timeline (ou le tween de niveau supérieur), pas sur les tweens à l'intérieur d'une timeline.
À ne pas faire
- ❌ Enchaîner des animations avec delay alors qu'une timeline peut les séquencer ; préférer
gsap.timeline()et le paramètre de position pour les animations multi-étapes. - ❌ Oublier de passer defaults (par ex.
defaults: { duration: 0.5, ease: "power2.out" }) lorsque de nombreux tweens enfants partagent la même durée ou le même easing. - ❌ Oublier que la duration sur le constructeur de la timeline n'est pas la même que la durée d'un tween ; la "durée" de la timeline est déterminée par ses enfants.
- ❌ Imbriquer des animations qui contiennent un ScrollTrigger ; les ScrollTriggers doivent uniquement être sur les Tweens/Timelines de niveau supérieur.