إضافات Gsap

# إضافات GSAP

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

طبقها عند استخدام أو مراجعة التعليمات البرمجية التي تستخدم إضافات GSAP: تسجيل الإضافات، التمرير إلى (scroll-to)، تحريكات الانعكاس/القلب (flip/FLIP)، العناصر القابلة للسحب (draggable)، SVG (DrawSVG، MorphSVG، MotionPath)، النص (SplitText، ScrambleText)، الفيزياء، إضافات التخفيف (easing plugins) (CustomEase، EasePack، CustomWiggle، CustomBounce)، أو GSDevTools. لدى ScrollTrigger مهارة خاصة بها (gsap-scrolltrigger).

**المهارات ذات الصلة:** بالنسبة للتحريكات الأساسية (core tweens) استخدم **gsap-core**؛ ل ScrollTrigger استخدم **gsap-scrolltrigger**؛ ل React استخدم **gsap-react**.

## الترخيص والتثبيت (مهم)

كل إضافة من إضافات GSAP **مجانية**، بما في ذلك الاستخدام التجاري. منذ [استحواذ Webflow على GSAP](https://gsap.com/blog/webflow-GSAP/)، لم يعد Club GSAP طبقة مدفوعة و**لا تتطلب أي إضافة عضوية، مفتاح ترخيص، أو رمز مصادقة** — وهذا يشمل الإضافات التي كانت حصرية ل Club سابقا (**SplitText**، **MorphSVG**، إلخ).

- ✅ قم بتثبيت كل شيء من حزمة npm العامة `gsap`: `npm install gsap`. جميع الإضافات متضمنة — قم باستيرادها ك `gsap/SplitText`، `gsap/MorphSVGPlugin`، إلخ. - ❌ لا تقم بإنشاء ملف `.npmrc` باستخدام رمز مصادقة GreenSock، أو اقتراح سجل `npm.greensock.com` الخاص، أو إخبار المستخدمين بالتسجيل في Club GSAP للوصول إلى إضافة. تلك التعليمات قديمة.

## تسجيل الإضافات

سجل كل إضافة مرة واحدة لكي تعرف GSAP (والمجمعات) تضمينها. استخدم **gsap.registerPlugin()** مع كل إضافة مستخدمة في المشروع:

```javascript import gsap from "gsap"; import { ScrollToPlugin } from "gsap/ScrollToPlugin"; import { Flip } from "gsap/Flip"; import { Draggable } from "gsap/Draggable";

gsap.registerPlugin(ScrollToPlugin, Flip, Draggable); ```

- ✅ سجل قبل استخدام الإضافة في أي تحريك (tween) أو استدعاء API. - ✅ في React، سجل على المستوى الأعلى أو مرة واحدة في التطبيق (مثل قبل أول استخدام ل useGSAP)؛ لا تسجل داخل مكون يعاد عرضه. useGSAP هي إضافة تحتاج إلى التسجيل قبل الاستخدام.

## التمرير (Scroll)

### ScrollToPlugin

تحرك موضع التمرير (النافذة أو عنصر قابل للتمرير). استخدمه ل "التمرير إلى عنصر" أو "التمرير إلى موضع" بدون ScrollTrigger.

```javascript gsap.registerPlugin(ScrollToPlugin);

gsap.to(window, { duration: 1, scrollTo: { y: 500 } }); gsap.to(window, { duration: 1, scrollTo: { y: "#section", offsetY: 50 } }); gsap.to(scrollContainer, { duration: 1, scrollTo: { x: "max" } }); ```

**ScrollToPlugin — الإعدادات الرئيسية (كائن scrollTo):**

| الخيار | الوصف | |--------|-------------| | `x`, `y` | موضع التمرير المستهدف (رقم)، أو `"max"` للحد الأقصى | | `element` | محدد أو عنصر للتمرير إليه (للتمرير إلى العرض) | | `offsetX`, `offsetY` | إزاحة بالبكسل من الموضع المستهدف |

### ScrollSmoother

غلاف تمرير سلس (ينعم التمرير الأصلي). يتطلب ScrollTrigger وهيكل DOM محدد (غلاف محتوى + غلاف سلس). استخدمه عندما تكون هناك حاجة إلى تمرير سلس بنمط الزخم. راجع وثائق GSAP للإعداد؛ سجل بعد ScrollTrigger. سيبدو هيكل DOM كالتالي:

```html <body> <div id="smooth-wrapper"> <div id="smooth-content"> <!--- ALL YOUR CONTENT HERE ---> </div> </div> <!-- position: fixed elements can go outside ---> </body> ```

## DOM / واجهة المستخدم (UI)

### Flip

التقط الحالة باستخدام `Flip.getState()`، ثم طبق التغييرات (مثل تغييرات التخطيط أو الفئة)، ثم استخدم `Flip.from()` للتحريك من الحالة السابقة إلى الحالة الجديدة (FLIP: First, Last, Invert, Play). استخدمه عند التحريك بين حالتين تخطيطيتين (قوائم، شبكات، موسعة/مطوية).

```javascript gsap.registerPlugin(Flip);

const state = Flip.getState(".item"); // change DOM (reorder, add/remove, change classes) Flip.from(state, { duration: 0.5, ease: "power2.inOut" }); ```

**Flip — الإعدادات الرئيسية (متغيرات Flip.from):**

| الخيار | الوصف | |--------|-------------| | `absolute` | استخدم `position: absolute` أثناء الانعكاس (الافتراضي: `false`) | | `nested` | عندما يكون صحيحا، يتم قياس المستوى الأول فقط من العناصر الفرعية (أفضل للتحويلات المتداخلة) | | `scale` | عندما يكون صحيحا، قم بتوسيع العناصر لتناسب (يتجنب التمدد)؛ الافتراضي `true` | | `simple` | عندما يكون صحيحا، يتم تحريك الموضع/الحجم فقط (أسرع، أقل دقة) | | `duration`, `ease` | خيارات التحريك القياسية |

#### مزيد من المعلومات

https://gsap.com/docs/v3/Plugins/Flip

### Draggable

يجعل العناصر قابلة للسحب، الدوران، أو الرمي بالماوس/اللمس. استخدمه للمنزلقات، البطاقات، القوائم القابلة لإعادة الترتيب، أو أي تفاعل سحب.

```javascript gsap.registerPlugin(Draggable, InertiaPlugin);

Draggable.create(".box", { type: "x,y", bounds: "#container", inertia: true }); Draggable.create(".knob", { type: "rotation" }); ```

**Draggable — خيارات الإعدادات الرئيسية:**

| الخيار | الوصف | |--------|-------------| | `type` | `"x"`, `"y"`, `"x,y"`, `"rotation"`, `"scroll"` | | `bounds` | عنصر، محدد، أو `{ minX, maxX, minY, maxY }` لتقييد السحب | | `inertia` | `true` لتمكين الرمي/الزخم (يتطلب InertiaPlugin) | | `edgeResistance` | 0–1؛ المقاومة عند السحب خارج الحدود | | `cursor` | مؤشر CSS أثناء السحب | | `onDragStart`, `onDrag`, `onDragEnd` | دوال رد الاتصال (Callbacks)؛ تستقبل الحدث و tar |