در GSAP، Modifiers به شما اجازه می‌دهد مقادیر انیمیشن را در لحظه و پویا تغییر دهید، قبل از اینکه روی المان اعمال شود.
این قابلیت برای ساخت حرکت‌های دینامیک، چرخش نامحدود، محدودسازی موقعیت و رفتار پیشرفته بسیار مفید است.

🟢 1️⃣ ساختار پایه Modifiers

gsap.to(".box", {
  x: 500,
  duration: 2,
  modifiers: {
    x: function(value) {
      // value مقدار محاسبه شده توسط GSAP است
      return parseFloat(value) % 300;  // محدود کردن x تا 300
    }
  }
});

• مقدار ورودی (value) همیشه رشته است (string) یا عدد (number) بسته به ویژگی.

• مقدار return شده جایگزین مقدار اصلی می‌شود.

🟡 2️⃣ مثال: چرخش نامحدود (Looping Rotation)

gsap.to(".wheel", {
  rotation: 3600,
  duration: 5,
  modifiers: {
    rotation: function(r) {
      return r % 360;  // چرخش همیشه بین 0 تا 360 درجه
    }
  }
});

• این روش برای انیمیشن چرخش بی‌نهایت روی حلقه‌ها یا عقربه‌ها عالی است.

🟠 3️⃣ مثال: حرکت محدود روی صفحه

gsap.to(".ball", {
  x: 800,
  duration: 3,
  modifiers: {
    x: function(x) {
      // اگر بیشتر از 500 شود، دوباره به 0 برگردد
      return x > 500 ? 0 : x;
    }
  },
  repeat: -1
});

• Modifier اجازه می‌دهد مقدار انیمیشن را دستکاری و شرطی کنید.

🟣 4️⃣ ترکیب با Scale یا Opacity

gsap.to(".box", {
  x: 400,
  scale: 2,
  duration: 2,
  modifiers: {
    scale: (s, target) => Math.sin(s * 0.5) + 1  // مقیاس پویا و نوسانی
  },
  repeat: -1,
  yoyo: true
});

• پارامتر دوم target به شما دسترسی می‌دهد به عنصر DOM جاری.

🟤 نکات کلیدی

• محدود کردن مقادیر: می‌توانید محدودیت‌هایی روی x, y, rotation, scale و غیره ایجاد کنید.

• محاسبات پویا: می‌توان از توابع ریاضی مثل Math.sin, Math.cos و random استفاده کرد.

• چند ویژگی همزمان: می‌توانید چند ویژگی را Modifier بدهید:

modifiers: {
  x: x => x % 500,
  rotation: r => r % 360
}

• Stagger و Timeline: Modifier روی هر المان جداگانه اعمال می‌شود و با Timeline یا Stagger هماهنگ می‌شود.

⚡ مثال کامل با Timeline و Modifier

const tl = gsap.timeline({ repeat: -1 });

tl.to(".ball", {
  x: 1000,
  duration: 3,
  modifiers: {
    x: x => parseFloat(x) % 400
  },
  ease: "none"
});

• توپ تا 400px حرکت می‌کند و دوباره از ابتدا شروع می‌شود، بدون نیاز به کنترل دستی.

✅ جمع‌بندی

Modifiers یکی از قابلیت‌های قدرتمند GSAP است که به شما امکان کنترل دقیق و دینامیک روی هر ویژگی را می‌دهد.