البدء
ثبّت Glaze ومحرك الرسوم المتحركة الذي تستخدمه:
pnpm add glazejs gsap
# Or choose Motion:
pnpm add glazejs motion
يُعد كل من GSAP وMotion تبعية اختيارية من النظير. ولا تضمّن Glaze أيًا من المحركين.
التهيئة مرة واحدة
استدعِ glaze() بعد إدراج العناصر في DOM. مرّر المحرك وكل الإعدادات في استدعاء واحد:
import glaze from "glazejs"
import { gsap } from "gsap"
const root = document.querySelector("#app")
if (!root) throw new Error("Missing application root")
const animations = glaze({
lib: { gsap: { core: gsap } },
element: root,
breakpoints: { md: "(min-width: 768px)" },
defaults: { element: "duration-0.6" },
presets: { rise: "from:opacity-0|y-24" },
watch: { debounceTime: 200 },
})
<div id="app">
<div data-animate="preset-rise"></div>
<div data-animate="@md:preset-rise from:duration-1"></div>
</div>
يفحص هذا جذر DOM وينشئ رسومه المتحركة. يؤدي استدعاء glaze() مرة أخرى إلى إنشاء مثيل آخر؛ ولا يضيف إعدادات إلى مثيل موجود.
يعادل المحوّل الصريح API ذلك بالنسبة إلى GSAP:
import glaze from "glazejs"
import { createGsapAdapter } from "glazejs/gsap"
import { gsap } from "gsap"
const animations = glaze({ adapter: createGsapAdapter(gsap) })
لاستخدام Motion، استخدم createMotionAdapter({ animate, stagger }) من glazejs/motion. راجع دليل Motion لمعرفة الإعداد والميزات المدعومة. اختر إما adapter أو lib ضمن إعداد واحد.
الخيارات
| الخيار | الافتراضي | الغرض |
|---|---|---|
lib.gsap.core |
لا شيء | مثيل GSAP للإعداد الأصلي API. |
adapter |
لا شيء | محوّل GSAP أو Motion صريح؛ بديل لـ lib. |
element |
document |
جذر DOM المراد فحصه ومراقبته. |
dataAttribute |
"data-animate" |
السمة التي تحتوي على أدوات الرسوم المتحركة المساعدة. |
className |
لا شيء | بادئة الفئة لصياغة الفئة. |
breakpoints |
{ default: "(min-width: 1px)" } |
استعلامات الوسائط ذات الأسماء. |
defaults.tl |
لا شيء | إعدادات الجدول الزمني الافتراضية. |
defaults.element |
لا شيء | خصائص الرسوم المتحركة الافتراضية؛ لأدوات العنصر المساعدة الأولوية. |
presets |
لا شيء | سلاسل رسوم متحركة مسماة قابلة لإعادة الاستخدام. |
watch |
false |
مراقبة تغييرات DOM؛ يستخدم true مهلة إزالة ارتداد قدرها 500 مللي ثانية، أو مرّر { debounceTime }. |
يراقب وضع المراقبة إضافات العناصر الفرعية وإزالتها وتغييرات سمات الرسوم المتحركة داخل الجذر. وفي وضع الفئات، يراقب أيضًا تغييرات الفئات. يؤدي تغيير DOM ذي صلة إلى جدولة إعادة بناء مع مهلة إزالة ارتداد. ولا تؤدي تغييرات نمط الرسوم المتحركة المضمّن إلى إعادة البناء.
التحديث والتنظيف
احتفظ بالمثيل المُعاد لإدارة دورة حياته:
// Rescan after rendering new elements when watch is disabled.
animations.refresh()
// On component unmount or page teardown:
animations.destroy()
يعيد refresh() البناء باستخدام الإعداد الأصلي. يوقف destroy() الرسوم المتحركة، ويزيل المراقبين ومستمعي استعلامات الوسائط، ويستعيد الأنماط المضمنة الأصلية. يمكن استدعاؤه بأمان أكثر من مرة. لا يمكن إعادة تشغيل مثيل تم إتلافه باستخدام refresh()؛ أنشئ مثيلًا جديدًا عند التركيب مجددًا.
تتضمن القيمة المعادة أيضًا timelines وbreakpoints وstate الذي تم حله. يسجل كل إدخال في المخطط الزمني مخطط المحرك الزمني ومعرّفه واستعلام الوسائط وعنصر الجذر والإعدادات والعناصر المتحركة. أبقِ استدعاءات التشغيل الخاصة بالمحرك ضمن التعليمات البرمجية التي تعرف أي محول أنشأ المثيل.
قد تستبدل عمليات التحديث وإعادة البناء المتجاوبة كائنات المخطط الزمني الأصلية. اقرأ timelines[index].timeline الحالي عند التحكم في التشغيل بعد إعادة البناء بدلًا من الاحتفاظ بمرجع سابق للمخطط الزمني الأصلي.
CDN
نقاط الدخول العامة هي وحدات ES، ويمكن أيضًا تحميلها من CDN متوافق مع ESM:
import glaze from "https://esm.sh/glazejs"
import { gsap } from "https://esm.sh/gsap@3.15.0"
const animations = glaze({ lib: { gsap: { core: gsap } } })