در GSAP، وقتی چندین انیمیشن دارید که باید با زمان‌بندی دقیق و قابل کنترل پشت سر هم اجرا شوند، به جای زنجیره‌کردن ()gsap.to‌ های جداگانه از Timeline استفاده می‌کنیم.

🟢 ساخت یک Timeline

const tl = gsap.timeline();

• می‌توانید گزینه‌هایی مثل repeat, yoyo, defaults هنگام ساخت بدهید:

const tl = gsap.timeline({
  repeat: 1,         // تعداد تکرار (−1 = بی‌نهایت)
  yoyo: true,        // برگشت به حالت اول بعد از هر بار
  defaults: { ease: "power1.out", duration: 1 } // مقادیر پیش‌فرض
});

🟡 افزودن انیمیشن به Timeline

متدهای to(), from(), ()fromTo مستقیم روی تایم‌لاین استفاده می‌شوند:

tl.to(".box1", { x: 200 })
  .to(".box2", { y: 100 })
  .from(".title", { opacity: 0 });

• این انیمیشن‌ها به ترتیب اجرا می‌شوند.

🟠 همپوشانی و زمان شروع سفارشی

می‌توانید شروع هر مرحله را دقیق کنترل کنید:

tl.to(".box1", { x: 200, duration: 1 })
  .to(".box2", { y: 100, duration: 1 }, "-=0.5") // 0.5 ثانیه زودتر
  .to(".box3", { rotation: 360, duration: 1 }, "+=1"); // 1 ثانیه بعد

• " -=0.5 " یعنی نیم ثانیه قبل از پایان انیمیشن قبلی آغاز شود.

• " +=1 " یعنی 1 ثانیه بعد از پایان قبلی شروع شود.

🟣 کنترل پخش

یک متغیر نگه دارید تا بعداً کنترل کنید:

tl.pause();         // توقف
tl.play();          // ادامه
tl.reverse();       // پخش برعکس
tl.restart();       // از اول
tl.seek(1.5);       // رفتن به ثانیه مشخص
tl.progress(0.5);   // رفتن به 50٪ انیمیشن
tl.timeScale(2);    // دو برابر سریع‌تر

🟤 برچسب (Label)

برچسب‌ها کار زمان‌بندی را ساده می‌کنند:

tl.addLabel("startBoxes")
  .to(".box1", { x: 200 })
  .to(".box2", { y: 100 }, "startBoxes+=0.3"); // 0.3 ثانیه بعد از برچسب

حالا می‌توانید با tl.play("startBoxes") مستقیماً از آن نقطه پخش کنید.

🟡 تو در تو (Nested Timelines)

می‌توانید تایم‌لاین‌های کوچک را داخل تایم‌لاین اصلی قرار دهید:

const sub = gsap.timeline();
sub.to(".circle", { scale: 1.5 }).to(".circle", { scale: 1 });

tl.to(".box", { x: 100 })
  .add(sub, "+=0.5"); // ساب‌تایم‌لاین 0.5 ثانیه بعد

⚡ نمونه کامل

const tl = gsap.timeline({ defaults: { duration: 1, ease: "power2.out" } });

tl.from(".header", { y: -50, opacity: 0 })
  .to(".box1", { x: 200 })
  .to(".box2", { y: 100 }, "-=0.5")
  .fromTo(".footer", { opacity: 0 }, { opacity: 1, duration: 0.5 }, "+=0.5");

// کنترل
document.querySelector("#pauseBtn").addEventListener("click", () => tl.pause());
document.querySelector("#playBtn").addEventListener("click", () => tl.play());

✅ نکات کلیدی

• Timeline ترتیب و هماهنگی انیمیشن‌ها را بسیار ساده می‌کند.

• می‌توانید برای همه‌ی انیمیشن‌های داخل آن defaults تعریف کنید.

• کنترل‌هایی مثل pause, reverse, seek, timeScale قدرت زیادی برای تعامل به شما می‌دهند.

• از Label برای نام‌گذاری نقاط مهم و پرش به آن‌ها استفاده کنید.

• امکان ساخت Timeline تو در تو برای سازمان‌دهی پروژه‌های بزرگ وجود دارد.

با Timeline می‌توانید سناریوهای پیچیده مثل ورود چند المان، اسکرول انیمیشن و توالی‌های طولانی را دقیق و تمیز مدیریت کنید.