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

إنّ المكوّنات الإضافية التي توفّر مكتبات لتعريفات الكتل هي طريقة رائعة لمشاركة الوحدات القابلة لإعادة الاستخدام مع منتدى 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 المتوفّرة.
  • قريبًا، ستوفر Bluely أدوات تتيح لك تسجيل العناصر المُسجَّلة بالفعل دون خطأ. حتى ذلك الحين، قد ترغب في التحقق مما تم تسجيله بالفعل قبل تسجيل إضافة أو أداة تبديل أو مزيج أو ملء حقل بنفسك.
  • كن واضحًا بشأن أي متطلبات أساسية أو تبعيات مطلوبة من تعريفات المكونات الإضافية أو الكتل.

• ضع في اعتبارك توفير وظائف الإنشاء لكل كتلة من الكتل التي تقدمها.

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

  • إذا توفّرت دالة تثبيت للحظر، يمكنك قبول مَعلمة 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});
    

إضافة ملاحظات

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

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