الخط الزمني ل Gsap

# GSAP Timeline

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

طبقها عند بناء رسوم متحركة متعددة الخطوات، أو تنسيق عدة tweens بالتسلسل أو بالتوازي، أو عندما يسأل المستخدم عن الجداول الزمنية (timelines)، أو التسلسل، أو الرسوم المتحركة بنمط keyframe في GSAP.

**المهارات ذات الصلة:** ل tweens الفردية و eases استخدم **gsap-core**؛ للجداول الزمنية المدفوعة بالتمرير استخدم **gsap-scrolltrigger**؛ ل React استخدم **gsap-react**.

## إنشاء جدول زمني (Timeline)

```javascript const tl = gsap.timeline(); tl.to(".a", { x: 100, duration: 1 }) .to(".b", { y: 50, duration: 0.5 }) .to(".c", { opacity: 0, duration: 0.3 }); ```

بشكل افتراضي، يتم **إلحاق** tweens الواحد تلو الآخر. استخدم **معامل الموضع (position parameter)** لوضع tweens في أوقات محددة أو بالنسبة ل tweens أخرى.

## معامل الموضع (Position Parameter)

الوسيط الثالث (أو خاصية الموضع في vars) يتحكم في التنسيب:

- **مطلق (Absolute)**: `1` — يبدأ عند الثانية 1. - **نسبي (Relative) (افتراضي)**: `"+=0.5"` — بعد 0.5 ثانية من النهاية؛ `"-=0.2"` — قبل 0.2 ثانية من النهاية. - **تسمية (Label)**: `"labelName"` — عند تلك التسمية؛ `"labelName+=0.3"` — بعد 0.3 ثانية من التسمية. - **تنسيب (Placement)**: `"<"` — يبدأ عندما تبدأ الرسوم المتحركة المضافة حديثا؛ `">"` — يبدأ عندما تنتهي الرسوم المتحركة المضافة حديثا (افتراضي)؛ `"<0.2"` — بعد 0.2 ثانية من بدء الرسوم المتحركة المضافة حديثا.

أمثلة:

```javascript tl.to(".a", { x: 100 }, 0); // at 0 tl.to(".b", { y: 50 }, "+=0.5"); // 0.5s after last end tl.to(".c", { opacity: 0 }, "<"); // same start as previous tl.to(".d", { scale: 2 }, "<0.2"); // 0.2s after previous start ```

## إعدادات Timeline الافتراضية

مرر الإعدادات الافتراضية إلى ال timeline بحيث ترثها جميع ال tweens الفرعية:

```javascript const tl = gsap.timeline({ defaults: { duration: 0.5, ease: "power2.out" } }); tl.to(".a", { x: 100 }).to(".b", { y: 50 }); // both use 0.5s and power2.out ```

## خيارات Timeline (المنشئ)

- **paused: true** — إنشاء متوقف مؤقتا؛ استدع `.play()` للبدء. - **repeat**, **yoyo** — نفس ال tweens؛ تطبق على ال timeline بأكمله. - **onComplete**, **onStart**, **onUpdate** — دوال رد الاتصال على مستوى ال timeline. - **defaults** — متغيرات مدمجة في كل tween فرعي.

## التسميات (Labels)

أضف واستخدم التسميات لتسلسل قابل للقراءة والصيانة:

```javascript tl.addLabel("intro", 0); tl.to(".a", { x: 100 }, "intro"); tl.addLabel("outro", "+=0.5"); tl.to(".b", { opacity: 0 }, "outro"); tl.play("outro"); // start from "outro" tl.tweenFromTo("intro", "outro"); // pauses the timeline and returns a new Tween that animates the timeline's playhead from intro to outro with no ease. ```

## جداول زمنية متداخلة (Nesting Timelines)

يمكن أن تحتوي الجداول الزمنية على جداول زمنية أخرى.

```javascript const master = gsap.timeline(); const child = gsap.timeline(); child.to(".a", { x: 100 }).to(".b", { y: 50 }); master.add(child, 0); master.to(".c", { opacity: 0 }, "+=0.2"); ```

## التحكم في التشغيل

- **tl.play()** / **tl.pause()** - **tl.reverse()** / **tl.progress(1)** ثم **tl.reverse()** - **tl.restart()** — من البداية. - **tl.time(2)** — الانتقال إلى الثانية 2. - **tl.progress(0.5)** — الانتقال إلى 50%. - **tl.kill()** — إنهاء ال timeline و (افتراضيا) أبنائه.

## أفضل ممارسات GSAP الرسمية

- ✅ فضل استخدام الجداول الزمنية للتسلسل. - ✅ استخدم **معامل الموضع (position parameter)** (الوسيط الثالث) لوضع ال tweens في أوقات محددة أو بالنسبة للتسميات. - ✅ أضف **التسميات (labels)** باستخدام `addLabel()` لتسلسل قابل للقراءة والصيانة. - ✅ مرر **الإعدادات الافتراضية (defaults)** إلى منشئ ال timeline بحيث ترث ال tweens الفرعية المدة، ال ease، إلخ. - ✅ ضع ScrollTrigger على ال timeline (أو ال tween ذي المستوى الأعلى)، وليس على ال tweens داخل ال timeline.

## لا تفعل

- ❌ لا تربط الرسوم المتحركة ب **delay** عندما يمكن ل **timeline** تسلسلها؛ فضل `gsap.timeline()` ومعامل الموضع للرسوم المتحركة متعددة الخطوات. - ❌ لا تنس تمرير **الإعدادات الافتراضية (defaults)** (مثل `defaults: { duration: 0.5, ease: "power2.out" }`) عندما تشترك العديد من ال tweens الفرعية في نفس المدة أو ال ease. - ❌ لا تنس أن **duration** في منشئ ال timeline ليس هو نفسه مدة ال tween؛ يتم تحديد "duration" ال timeline بواسطة أبنائه. - ❌ لا تداخل الرسوم المتحركة التي تحتوي على ScrollTrigger؛ يجب أن تكون ScrollTriggers فقط على ال Tweens/Timelines ذات المستوى الأعلى.