در GSAP و دنیای انیمیشن و تعامل با اعداد، توابعی مانند clamp()، mapRange()، ()normalize و ()interpolate بسیار کاربردی هستند تا مقادیر را محدود، مقیاس‌دهی و تبدیل کنیم. این توابع به ویژه برای حرکت پویا، scroll animations و انیمیشن‌های واکنش‌گرا مفیدند.

🟢 1️⃣ ()clamp

• کاربرد: محدود کردن یک مقدار به بین حداقل و حداکثر مشخص.

• ساختار:

gsap.utils.clamp(min, max, value)

مثال:

let x = 500;
x = gsap.utils.clamp(0, 300, x);  // خروجی: 300

• اگر مقدار کمتر از min باشد → min برمی‌گردد

• اگر مقدار بیشتر از max باشد → max برمی‌گردد

🟡 2️⃣ ()mapRange

• کاربرد: نگاشت یک مقدار از یک بازه به بازه‌ای دیگر.

• ساختار:

gsap.utils.mapRange(fromMin, fromMax, toMin, toMax, value)

مثال:

let scroll = 150; // مقدار بین 0 و 300
let x = gsap.utils.mapRange(0, 300, 0, 600, scroll);
console.log(x); // خروجی: 300

• نگاشت خطی: مقدار ورودی 0–300 → خروجی 0–600

🟠 3️⃣ ()normalize

• کاربرد: مقیاس‌دهی یک مقدار به بازه [0,1].

• ساختار:

gsap.utils.normalize(min, max, value)

مثال:

let val = 75;
let normalized = gsap.utils.normalize(0, 100, val);
console.log(normalized); // خروجی: 0.75

• مقدار 0 → 0

• مقدار max → 1

• مقدار میانی → بین 0 و 1

🟣 4️⃣ ()interpolate

• کاربرد: ترکیب یا تبدیل یک مقدار از یک بازه به مقادیر دیگر، مشابه lerp یا tween دستی.

• ساختار ساده:

gsap.utils.interpolate(startValue, endValue, progress)

مثال:

let start = 0;
let end = 200;
let progress = 0.25; // درصد پیشرفت بین 0 و 1
let x = gsap.utils.interpolate(start, end, progress);
console.log(x); // خروجی: 50

• ترکیب چند مقدار:

gsap.utils.interpolate([0, 100, 200], [50, 150, 250], 0.5);
// خروجی: آرایه میانی بین دو آرایه

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

• ()clamp و ()normalize معمولاً با Scroll یا حرکت Drag استفاده می‌شوند.

• ()mapRange برای واسطه‌سازی مقادیر input → output بسیار مناسب است (مثلاً Scroll → Scale).

• ()interpolate برای Tweenهای سفارشی یا محاسبات پیچیده کاربرد دارد.

• این توابع اغلب با onUpdate یا modifiers GSAP ترکیب می‌شوند:

gsap.to(".box", {
  x: 1000,
  duration: 2,
  modifiers: {
    x: x => gsap.utils.clamp(0, 300, x)
  }
});

✅ جمع‌بندی

این توابع، پایه‌ای برای حرکات پویا، انیمیشن‌های واکنش‌گرا و کنترل دقیق Tweenها در GSAP هستند.