نشر مكتبات الحظر

إنّ الإضافات التي توفّر مكتبات لتعريفات الكتل هي طريقة رائعة لمشاركة الكتل القابلة لإعادة الاستخدام مع منتدى Blockly. لقد وضعنا هذه الإرشادات لجعل مكتبة الحظر متنوعة ومفيدة قدر الإمكان.

الإرشادات

• اجعل من السهل على المستخدمين تثبيت جميع الكتل، وامنحهم إمكانية تثبيت كتل معيّنة أو أجزاء من الكتل فقط.
  • تسهيل تثبيت كل العناصر: يمكنك إجراء ذلك من خلال توفير دالة تعمل على تثبيت كل قطعة يتطلبها تعريف كتلة واحد (مثل المُعدِّلات والإضافات والعناصر المختلطة والحقول وما إلى ذلك). يمكنك أيضًا توفير دالة ستثبّت جميع الكتل التي يوفّرها المكوّن الإضافي في آنٍ واحد.
  • إتاحة اختيار أجزاء معيّنة: يجب تصدير جميع أجزاء تعريف الكتلة بشكل منفصل، حتى يتمكن المستخدم من استيراد الأجزاء التي يحتاجها فقط لإنشاء وحدة مخصَّصة مشابهة.
• تجنَّب استخدام التأثيرات الجانبية في المكوّن الإضافي.
  • يجب عدم تثبيت الكتل والحقول والإضافات والقطع الأخرى كأحد أثر الجانبي لتحميل المكوّن الإضافي. يجب أن يحافظ المستخدمون على التحكّم في العناصر التي يتم تثبيتها ووقت تثبيتها. يتيح ذلك للمستخدمين استيراد القطع التي يحتاجونها بدون القلق من تثبيت القطع التي لا يحتاجونها.

• استخدِم سجلّ حقول JSON بدلاً من إنشاء حقول جديدة مباشرةً.

  • لا يُنصح بإنشاء مثيل لحقل جديد مباشرةً:

      const myCustomBlock = {
        init: function() {
          this.appendDummyInput()
              .appendField(new Blockly.FieldNumber(123), 'NAME');
        }
      }
    

  • إجراء ننصح به - سجلّ حقل JSON:

      export const myCustomBlock = {
        init: function() {
          this.appendDummyInput()
              .appendField(Blockly.fieldRegistry.fromJson({
                  name: 'field_number',
                  value: 123,
                }), 'NAME');
        }
      }
    

  • يسهِّل استخدام سجلّ الحقول على المستخدم استبدال تنفيذ الحقل المستخدَم في الحظر بدون الحاجة إلى تغيير تعريف الحظر.

• لا تضع افتراضات حول ما قام المستخدم بتثبيته بالفعل.

  • إذا كان المكوّن الإضافي يتطلّب حقلًا مخصّصًا أو مكوّنًا إضافيًا آخر، سجِّل هذين الحقول بنفسك في دالة install المقدَّمة.
  • قريبًا، ستوفر Blockly أدوات تتيح لك تسجيل العناصر المسجلة بالفعل دون خطأ. وحتى ذلك الحين، قد تحتاج إلى التحقق مما تم تسجيله بالفعل قبل تسجيل إضافة أو مغير أو مزيج أو حقل بنفسك.
  • يجب أن تكون واضحًا بشأن أي متطلبات أساسية أو تبعيات مطلوبة من أجل تعريفات المكوّن الإضافي أو الكتلة.

• ننصحك بتوفير دوالّ إنشاء لكلّ عنصر من العناصر التي تقدّمها.

  • من خلال توفير دوالّ إنشاء تعمل تلقائيًا، يسهُل على المستخدمين استخدام الكتل بدون الحاجة إلى فهم بنيتها وتصميمها. إذا كان عليهم كتابة دوال المنشئ الخاصة بهم، فقد يؤدي ذلك إلى قيام كل مستخدم بعمل متكرر.
  • JavaScript هي اللغة الأكثر استخدامًا في Blockly، لذا إذا أردت اختيار لغة واحدة فقط، ننصحك باستخدام JavaScript، ما لم تكن وحداتك مصمّمة بلغة معيّنة، مثل تنفيذ مكتبة Python.
  • ننصحك بنشر مشاكل "مطلوب مساعدة" للغات التي يتعذّر عليك تنفيذ دوالّ المولدات لها، وقبول طلبات سحب لأجل هذه اللغات إذا ساهم فيها أحد المستخدمين.

  • إذا قدّمت دالة تثبيت للوحدة، يمكنك قبول معلَمة generators اختيارية. إذا أرسل مستخدم مثيلًا لبرنامج إنشاء محتوى تتيحه، يمكنك تثبيت وظيفة برنامج إنشاء الرموز البرمجية للوحدات تلقائيًا وتنفيذ المهام ذات الصلة، مثل إضافة الكلمات المحجوزة:

      // Your plugin's install function
      export const installMyCustomBlock(generators = {}) {
        Blockly.defineBlocks({my_custom_block: myCustomBlock});
        if (generators.javascript) {
          generators.javascript.forBlock['my_custom_block'] = myCustomGeneratorFunction;
          generators.javascript.addReservedWords('specialReservedWord');
        }
      }
    
      // How a user may install your block
      import {javascriptGenerator} from 'blockly/javascript';
      import {installMyCustomBlock} from 'blockly-cool-blocks-plugin';
      // installs the block definition and the javascript block-code generator
      installMyCustomBlock({javascript: javascriptGenerator});
    

ملاحظات

إذا كانت لديك أسئلة حول كيفية اتّباع هذه الإرشادات على أفضل وجه في المكوّن الإضافي، يُرجى إخبارنا بها في المنتدى. يسرّنا الاطّلاع على مكتبات المحتوى المحظور وتقديم ملاحظات بشأنها.

يُرجى العلم أنّ بعض المكوّنات الإضافية التابعة لجهة خارجية التي تقدّم تعريفات للعناصر المحظورة لا تتبع حاليًا هذه الإرشادات، ولكنّ المكوّنات الإضافية الجديدة ستلتزم بها، ونخطّط لنقل المكوّنات الإضافية الحالية.