التأثيرات هي صفحات ويب

التأثيرات في SignalRGB، المعروفة باسم Lightscripts، هي في جوهرها صفحات ويب تتفاعل مع SignalRGB API، ويجب أن تلتزم ببعض القواعد البسيطة لتعمل بشكل صحيح. يتطلب كل Lightscript ثلاثة وسوم HTML أساسية: <head> و<body> و<script>.

<head>

يجب أن يحتوي هذا القسم على أي وسوم <meta> ضرورية. وكما هو مفصّل في قسم “مرجع API”، يمكن لهذه الوسوم إنشاء حقول إدخال للمستخدم (مثل منزلقات درجة اللون، ومحددات الأرقام، وغيرها) أو الوصول إلى SignalRGB API لسحب المدخلات المرئية من تطبيقك الأساسي. بالإضافة إلى ذلك، يعيّن وسم <title> في هذا القسم اسمًا لتأثيرك داخل تطبيق Signal.

لنعد إلى المثال السابق لفهم أوضح:

<head>
    <title>Hue Cycle</title>
    <meta description="Stock hue cycle."/>
    <meta publisher="WhirlwindFX" />
    <meta property="speed" label="Cycle Speed" type="number" min="1" max="10" default="2">
</head>

يتضمن هذا الترويس أربعة وسوم: وسم <title>، وثلاثة وسوم <meta> تغطي الوصف والناشر ومنزلق أرقام أساسيًا. وبينما تكون ترويسات التأثيرات الثابتة صغيرة عادةً، فإن التأثيرات التي تستجيب للأحداث على الشاشة قد تتضمن عشرات العدّادات، لكل منها إعدادات دقة متعددة. من المهم أن تحافظ على التنظيم وتتبع اصطلاحات تسمية جيدة.

<head>

<body>

يحتوي الجسم على عنصر واحد فقط - وسم <canvas>. السمات الأساسية لهذا الوسم هي id، التي تُستخدم لجلب canvas في السكربت، بالإضافة إلى width وheight. الأبعاد القياسية في SignalRGB هي 320px للعرض و200px للارتفاع.

<body style="margin: 0; padding: 0;">
    <canvas id="exCanvas" width="320" height="200"></canvas>
</body>

<body>

<script>

في هذا الوسم يحدث السحر. هناك ثلاثة أقسام أساسية في هذا السكربت، إلى جانب دالتين يجب اعتبارهما أساسيتين (STANDARD) لمطوري Lightscript: update وwindow.requestAnimationFrame.

تعريفات المتغيرات

يجب تعريف جميع المتغيرات على مستوى السكربت معًا لتبسيط عملية التطوير. وفي المستقبل، سيشمل ذلك أيضًا تعريفات العدّادات، لكن لدينا الآن مجموعة بسيطة.

• var c: يُستخدم لجلب وسم canvas الذي أنشأناه سابقًا.
• var ctx: السياق ثنائي الأبعاد (2D context) لعنصر canvas، وهو المساحة القابلة للتعديل لتأثيرك.
• height وwidth وhue: تُعرَّف هنا لتبسيط العملية.

استدعاء التحديث الأولي

في أسفل كتلة الشيفرة، أشير إلى window.requestAnimationFrame(update). و”Update” هو اسم الدالة التي تتولى تفاصيل الرسم المتحرك. فالحالة المحدّثة في كل إطار تخلق وهم الحركة لدى المشاهدين.

الطريقة المستخدمة هنا بالغة الأهمية: نظرًا لأن كل عملية في دالة update تستغرق وقتًا قصيرًا للتنفيذ، فإن استدعاء update() مباشرة قد يسبب تأخيرًا في الرسوم المتحركة. على سبيل المثال، قد يعتقد الاستدعاء الراجع الأول أن 100ms قد مرت، والتالي 110ms، وهكذا.

باستخدام window.requestAnimationFrame، يُمرَّر الطابع الزمني الحالي إلى دالة الاستدعاء الراجع والاستدعاءات المتداخلة فيها، مما يحافظ على حالة الرسم المتحرك رغم فجوات التنفيذ الصغيرة.

باختصار، استخدم الطريقة window.requestAnimationFrame(callback) لتحديث رسمك المتحرك!

دالة Update

هذه الدالة محورية لعمل أي Lightscript، ويجب أن تكون بسيطة ومبسّطة قدر الإمكان لأنها تعمل في كل إطار. بعد التحميل الأولي للسكربت واستدعاء الدالة، ستستمر update في العمل من خلال استدعائها الداخلي لـ window.requestAnimationFrame.

في هذا المثال، ينفّذ كل إطار أربع عمليات رئيسية:

1. تعيين نمط ملء canvas باستخدام ctx.fillStyle. يمكن أن يكون ذلك لونًا أو نقشًا أو تدرجًا، وسيظل ساريًا حتى يُستبدل باستدعاء ctx.fillStyle التالي.
2. إنشاء مستطيل (بنمط الملء المعيّن سابقًا) باستخدام ctx.fillRect(x, y, width, height). في هذه الحالة، يمثل المستطيل canvas بالكامل.
3. زيادة hue بمقدار speed، وهو متغير إدخال المستخدم الموجود في الترويس.
4. حصر hue ضمن النطاق 0-360 ليتوافق مع معيار HSL (درجة اللون، التشبع، الإضاءة).

<script>
    // Variable Declarations -------------------------
    // Get the canvas element from the DOM
    var c = document.getElementById("exCanvas");
    var ctx = c.getContext("2d");
    var width = 320;
    var height = 200;
    var hue = 0;

    // Update function --------------------------------
    function update()
    {
      // 1
      ctx.fillStyle = 'hsl('+ hue + ', 100%, 50%)';
      // 2
      ctx.fillRect(0, 0, width , height);
      // 3
      hue+=(speed / 4);
      // 4
      if (hue > 360) { hue = hue % 360; }
      // Re-call the function
      window.requestAnimationFrame(update);
    }

    // Initial update call ----------------------------
    window.requestAnimationFrame(update);
</script>

هذا النمط العام (تعيين الملء، رسم الشكل، تعديل المتغيرات) هو المعيار في الرسوم المتحركة على canvas.

• إذا كان اللون خاطئًا، فقد فاتك تعيين نمط الملء.
• إذا كان الشكل خاطئًا، فقد فاتك رسم الشكل.
• إذا لم يتغير شيء بمرور الوقت، فأنت لم تعدّل متغيراتك.

لمزيد من التفاصيل ونصائح استكشاف الأخطاء وإصلاحها، راجع صفحتنا التالية حول HTML5 + JS.

<script>