أدوات Gsap

# gsap.utils

## متى تستخدم هذه المهارة

تطبق عند كتابة أو مراجعة الكود الذي يستخدم **gsap.utils** للتعامل مع العمليات الحسابية، المصفوفات/المجموعات، تحليل الوحدات، أو تعيين القيم في الرسوم المتحركة (مثل تعيين التمرير إلى قيمة، العشوائية، الالتصاق بالشبكة، أو تطبيع المدخلات).

**المهارات ذات الصلة:** تستخدم مع **gsap-core**، **gsap-timeline**، و **gsap-scrolltrigger** عند بناء الرسوم المتحركة؛ توجد CustomEase وأدوات التسهيل الأخرى في **gsap-plugins**.

## نظرة عامة

توفر **gsap.utils** مساعدات نقية؛ لا حاجة للتسجيل. تستخدم في متغيرات tween (مثل القيم المستندة إلى الدالة)، في استدعاءات ScrollTrigger أو Observer، أو في أي JavaScript يدير GSAP. جميعها موجودة على **gsap.utils** (مثل `gsap.utils.clamp()`).

**إغفال القيمة: شكل الدالة.** تقبل العديد من الأدوات المساعدة القيمة المراد تحويلها كحجة **أخيرة**. إذا أغفلت تلك الحجة، فإن الأداة المساعدة ترجع **دالة** تقبل القيمة لاحقا. استخدم شكل الدالة عندما تحتاج إلى تقييد، تعيين، تطبيع، أو تثبيت العديد من القيم بنفس التكوين (على سبيل المثال، في معالج mousemove أو استدعاء tween). **استثناء: random()** — مرر **true** كحجة أخيرة للحصول على دالة قابلة لإعادة الاستخدام (لا تغفل القيمة)؛ انظر [random()](https://gsap.com/docs/v3/GSAP/UtilityMethods/random/).

```javascript // With value: returns the result gsap.utils.clamp(0, 100, 150); // 100

// Without value: returns a function you call with the value later let c = gsap.utils.clamp(0, 100); c(150); // 100 c(-10); // 0 ```

## التقييد والنطاقات

### clamp(min, max, value?)

يقيد قيمة بين الحد الأدنى والأقصى. أغفل **value** للحصول على دالة: `clamp(min, max)(value)`.

```javascript gsap.utils.clamp(0, 100, 150); // 100 gsap.utils.clamp(0, 100, -10); // 0

let clampFn = gsap.utils.clamp(0, 100); clampFn(150); // 100 ```

### mapRange(inMin, inMax, outMin, outMax, value?)

يعين قيمة من نطاق إلى آخر. يستخدم عند تحويل موضع التمرير، التقدم (0-1)، أو نطاق الإدخال إلى نطاق رسوم متحركة. أغفل **value** للحصول على دالة: `mapRange(inMin, inMax, outMin, outMax)(value)`.

```javascript gsap.utils.mapRange(0, 100, 0, 500, 50); // 250 gsap.utils.mapRange(0, 1, 0, 360, 0.5); // 180 (progress to degrees)

let mapFn = gsap.utils.mapRange(0, 100, 0, 500); mapFn(50); // 250 ```

### normalize(min, max, value?)

يرجع قيمة مطبعة إلى 0-1 للنطاق المحدد. عكس التعيين عندما يكون النطاق المستهدف 0-1. أغفل **value** للحصول على دالة: `normalize(min, max)(value)`.

```javascript gsap.utils.normalize(0, 100, 50); // 0.5 gsap.utils.normalize(100, 300, 200); // 0.5

let normFn = gsap.utils.normalize(0, 100); normFn(50); // 0.5 ```

### interpolate(start, end, progress?)

يستقري بين قيمتين عند تقدم معين (0-1). يتعامل مع الأرقام، الألوان، والكائنات ذات المفاتيح المتطابقة. أغفل **progress** للحصول على دالة: `interpolate(start, end)(progress)`.

```javascript gsap.utils.interpolate(0, 100, 0.5); // 50 gsap.utils.interpolate("#ff0000", "#0000ff", 0.5); // mid color gsap.utils.interpolate({ x: 0, y: 0 }, { x: 100, y: 50 }, 0.5); // { x: 50, y: 25 }

let lerp = gsap.utils.interpolate(0, 100); lerp(0.5); // 50 ```

## عشوائي وتثبيت

### random(minimum, maximum[, snapIncrement, returnFunction]) / random(array[, returnFunction])

يرجع رقما عشوائيا في النطاق **minimum**–**maximum**، أو عنصرا عشوائيا من **array**. يثبت **snapIncrement** الاختياري النتيجة إلى أقرب مضاعف (على سبيل المثال `5` ← مضاعفات 5). **للحصول على دالة قابلة لإعادة الاستخدام**، مرر **true** كحجة أخيرة (**returnFunction**)؛ لا تأخذ الدالة المرتجعة أي حجج وترجع قيمة عشوائية جديدة في كل مرة. هذه هي الأداة المساعدة الوحيدة التي تستخدم `true` لشكل الدالة بدلا من إغفال القيمة.

```javascript // immediate value: number in range gsap.utils.random(-100, 100); // e.g. 42.7 gsap.utils.random(0, 500, 5); // 0–500, snapped to nearest 5

// reusable function: pass true as last argument let randomFn = gsap.utils.random(-200, 500, 10, true); randomFn(); // random value in range, snapped to 10 randomFn(); // another random value

// array: pick one value at random gsap.utils.random(["red", "blue", "green"]); // "red", "blue", or "green" let randomFromArray = gsap.utils.random([0, 100, 200], true); randomFromArray(); // 0, 100, or 200 ```

**شكل السلسلة في متغيرات tween:** استخدم `"random(-100, 100)"`، `"random(-100, 100, 5)"`، أو `"random([0, 100, 200])"`؛ يقوم GSAP بتقييمها لكل هدف.

```javascript gsap.to(".box", { x: "random(-100, 100, 5)", duration: 1 }); gsap.to(".item", { backgroundColor: "random([red, blue, green])" }); ```

### snap(snapTo, value?)

يثبت قيمة إلى أقرب مضاعف ل **snapTo**، أو إلى أقرب قيمة في مصفوفة من القيم المسموح بها. أغفل **value** للحصول على دالة: `snap(snapTo)(value)` (أو `snap(snapArray)(value)`).

```javascript gsap.utils.snap(10, 23); // 20 gsap.utils.snap(0.25, 0.7); // 0.75 gsap.utils.snap([0, 100, 200], 150); // 100 or 200 (nearest in array)

let snapFn = gsap.utils.snap(10); snapFn(23); // 20