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

تُعد المكوّنات الإضافية التي توفر مكتبات لتعريفات الكتل طريقة رائعة لمشاركة والمكعبات القابلة لإعادة الاستخدام مع منتدى 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.common.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});
    

ملاحظات

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

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