در GSAP، توابع کمکی مانند distribute()، pipe() و snap() ابزارهای حرفه‌ای برای مدیریت مقادیر پویا و انیمیشن‌های گروهی هستند. این توابع به شما کمک می‌کنند تا مقادیر را محاسبه، تبدیل یا توزیع کنید و رفتار انیمیشن‌ها را دقیق و پیش‌بینی‌پذیر کنید.

🟢 1️⃣ ()distribute

• کاربرد: توزیع مقادیر بین چند المان به صورت خطی، مرکزی، شعاعی یا سفارشی.

• ساختار پایه:

gsap.utils.distribute(options)

مثال:

gsap.to(".box", {
  x: gsap.utils.distribute({ base: 100, amount: 200 }),
  duration: 1
});

• آرگومان options می‌تواند شامل موارد زیر باشد:

  • base → مقدار پایه

  • amount → مقدار نهایی برای توزیع

  • each → فاصله بین هر المان

  • from → مرکز توزیع (start, center, end, عدد یا index)

مثال با from:

gsap.to(".box", {
  x: gsap.utils.distribute({ base: 0, amount: 400, from: "center" }),
  duration: 1
});

🟡 2️⃣ ()pipe

• کاربرد: ایجاد زنجیره‌ای از توابع که روی مقدار اجرا می‌شوند، مشابه pipeline در برنامه‌نویسی.

• ساختار:

gsap.utils.pipe(fn1, fn2, fn3, ...)

مثال:

const double = x => x * 2;
const clamp = x => gsap.utils.clamp(0, 100, x);

const transform = gsap.utils.pipe(double, clamp);

console.log(transform(30)); // 60
console.log(transform(80)); // 100 (clamped)

• می‌توان از آن در modifiers یا Tween dynamic values استفاده کرد.

🟠 3️⃣ ()snap

• کاربرد: چسباندن مقادیر به نزدیک‌ترین Step یا مقدار مشخص، مشابه clamp ولی با گسستگی.

• ساختار:

gsap.utils.snap(stepOrArray, value)

مثال با step:

let x = gsap.utils.snap(50, 123); 
console.log(x); // 100 (نزدیک‌ترین مضرب 50)

مثال با آرایه:

let colors = ["red","green","blue"];
let chosen = gsap.utils.snap(colors, "yellow");
console.log(chosen); // "red" (نزدیک‌ترین مقدار در آرایه)

• کاربرد عملی: انیمیشن کارت‌ها، چرخش گسسته، یا محدود کردن مقادیر input → output.

🟤 ترکیب این توابع با GSAP

Distribute + Tween

gsap.to(".box", {
  x: gsap.utils.distribute({ base: 0, amount: 400, from: "center" }),
  duration: 1
});

Snap + Modifier

gsap.to(".ball", {
  x: 500,
  duration: 2,
  modifiers: { x: x => gsap.utils.snap(100, parseFloat(x)) },
  repeat: -1
});

Pipe در Modifiers

gsap.to(".box", {
  x: 500,
  modifiers: { x: gsap.utils.pipe(x => parseFloat(x) * 2, x => gsap.utils.clamp(0, 800, x)) },
  duration: 2
});

✅ جمع‌بندی

این توابع کمک می‌کنند تا انیمیشن‌های گروهی، پویا و با رفتار پیش‌بینی‌پذیر بسازید، بدون نیاز به محاسبات پیچیده دستی.