آموزش جامع GSAP

📚معرفی و نصب

GSAP (GreenSock Animation Platform) قوی‌ترین و محبوب‌ترین کتابخانه انیمیشن جاوااسکریپت است. برخلاف CSS Animations، کنترل دقیق روی زمان‌بندی، ترتیب و مقادیر دارد و با هر فریم‌ورکی کار می‌کند.

نصب

<!-- فایل لوکال -->
<script src="gsap.min.js"></script>

<!-- یا CDN -->
<script src="https://cdn.jsdelivr.net/npm/gsap@3.12.5/dist/gsap.min.js"></script>

اولین انیمیشن

// حرکت به سمت راست در ۱ ثانیه
gsap.to("#myBox", {
  x: 200,
  duration: 1,
  ease: "power2.out"
});

▶متدهای پایه

// gsap.to — از موقعیت فعلی به مقصد
gsap.to("#box", { x: 200, rotation: 45, duration: 1 });

// gsap.from — ورود از بیرون صفحه
gsap.from("#box", { x: 300, opacity: 0, duration: 1 });

// gsap.fromTo — کنترل کامل start → end
gsap.fromTo("#box",
  { x: -200, opacity: 0 },          // from
  { x: 0,    opacity: 1, duration: 1.5 } // to
);

// gsap.set — بدون انیمیشن (ریست)
gsap.set("#box", { x: 0, opacity: 1, clearProps: "all" });

🎨ویژگی‌های قابل انیمیشن

GSAP می‌تواند تقریباً هر ویژگی CSS و transform را انیمیت کند:

📈Easing — زمان‌بندی انیمیشن

Easing نحوه شتاب‌گیری و کاهش سرعت را تعریف می‌کند. تفاوت یک انیمیشن معمولی و احساسی همین است.

قانون نام‌گذاری

// فرمت: "نوع.جهت"
// جهت: in (شروع کند) | out (پایان کند) | inOut (هر دو)

gsap.to("#box", { x: 300, duration: 1.5, ease: "bounce.out"      });
gsap.to("#box", { x: 300, duration: 1.5, ease: "elastic.out(1,0.3)" });
gsap.to("#box", { x: 300, duration: 1.5, ease: "back.out(1.7)"      });
gsap.to("#box", { x: 300, duration: 1.5, ease: "power4.inOut"       });
gsap.to("#box", { x: 300, duration: 1.5, ease: "none"               }); // خطی

📈Timeline — زنجیره انیمیشن‌ها

Timeline قدرتمندترین ویژگی GSAP است. چندین انیمیشن را پشت‌سر‌هم یا همزمان تعریف کنید و کل زنجیره را با یک دستور کنترل کنید.

const tl = gsap.timeline({
  defaults: { duration: 0.6, ease: "power2.out" }  // پیش‌فرض برای همه
});

tl.from("#title",    { y: -50, opacity: 0 })
  .from("#subtitle", { y: -30, opacity: 0 })
  .from("#btn",      { scale: 0,  opacity: 0 }, "-=0.2")  // 0.2s قبل از پایان
  .from("#img",      { x: 100,  opacity: 0 }, "<");     // همزمان با قبلی

★Stagger — انیمیشن ترتیبی

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

// ساده — همه .card ها با تأخیر ۱۵۰ms
gsap.from(".card", {
  opacity: 0, y: 50, duration: 0.5,
  stagger: 0.15
});

// پیشرفته — توزیع از مرکز grid
gsap.from(".grid-item", {
  opacity: 0, scale: 0.5,
  stagger: {
    amount: 1.5,    // کل زمان توزیع
    grid:   [2, 5],  // ردیف × ستون
    from:   "center" // شروع از مرکز (end, start, random)
  }
});

⚙کنترل پخش (Playback)

همه متدهای GSAP یک Tween Instance برمی‌گردانند که می‌توان آن را کنترل کرد.

const tween = gsap.to("#box", {
  x: 300, rotation: 360,
  duration: 3, ease: "none",
  repeat: -1,   // -1 = بی‌نهایت
  yoyo: true,   // رفت و برگشت
  paused: true  // شروع نشده
});

tween.play();             // پخش
tween.pause();            // توقف
tween.reverse();          // برعکس
tween.restart();          // از ابتدا
tween.seek(1.5);          // رفتن به ثانیه ۱.۵
tween.timeScale(2);       // دو برابر سرعت
tween.timeScale(0.5);     // نصف سرعت
tween.kill();              // حذف کامل
tween.progress()           // درصد پیشرفت (0 تا 1)

📞Callback و تکرار

Callback‌های اصلی

gsap.to("#box", {
  x: 300, duration: 1,

  onStart:    () => console.log('شروع شد'),
  onComplete: () => console.log('تمام شد'),
  onUpdate:   () => console.log('در حال اجرا'),
  onRepeat:   () => console.log('تکرار شد'),
  onReverseComplete: () => console.log('برعکس تمام شد'),
});

تکرار و Yoyo

gsap.to("#box", {
  x: 200, duration: 0.8,
  repeat: 3,       // ۳ بار تکرار (مجموعاً ۴ بار اجرا)
  repeatDelay: 0.5, // فاصله بین تکرارها
  yoyo: true        // رفت و برگشت
});

// تکرار بی‌نهایت
gsap.to("#icon", { rotation: 360, duration: 2, repeat: -1, ease: "none" });

// delay — شروع با تأخیر
gsap.to("#box", { x: 200, duration: 1, delay: 0.5 });

// gsap.delayedCall — تابع با تأخیر
gsap.delayedCall(2, () => console.log('۲ ثانیه گذشت'));

🔥نکات حرفه‌ای

حذف ایمن انیمیشن‌ها

// قبل از اجرای مجدد — جلوگیری از تداخل
gsap.killTweensOf("#box");

// حذف فقط یک ویژگی خاص
gsap.killTweensOf("#box", "x,opacity");

// پاک کردن transform ها بعد از انیمیشن
gsap.set("#box", { clearProps: "all" });

بهینه‌سازی Performance

/* CSS — GPU acceleration */
#box { will-change: transform; }

// در React / Vue — استفاده از gsap.context
useEffect(() => {
  const ctx = gsap.context(() => {
    gsap.to(".item", { x: 100 });
  });
  return () => ctx.revert(); // cleanup
}, []);

پلاگین‌های مهم

🏆پروژه کامل — Hero Animation

ترکیب Timeline + Stagger + from برای ساخت یک Hero section حرفه‌ای:

const tl = gsap.timeline({ delay: 0.3 });

tl.from(".hero-title", { y: -40, opacity: 0, duration: 0.7, ease: "back.out(1.5)" })
  .from(".hero-sub",   { y: -20, opacity: 0, duration: 0.6 }, "-=0.3")
  .from(".hero-btn",   { scale: 0, opacity: 0, duration: 0.5, ease: "back.out(2)" }, "-=0.2")
  .from(".dot",        { scale: 0, opacity: 0, stagger: 0.1,  duration: 0.3 }, "-=0.2")
  .to(".dot", {
    y: -8, stagger: 0.1, duration: 0.4,
    ease: "power1.inOut", yoyo: true, repeat: -1
  });

🚀زمین بازی کد (Playground)

کد GSAP را همین‌جا ویرایش کن و انیمیشن را زنده ببین. tween، timeline و stagger را تغییر بده و ▶ اجرا را بزن. نسخهٔ ۳.۱۲.۵ آفلاین بارگذاری می‌شود.