إضافة حقل مكوّن إضافي إلى "مصنع الحظر"

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

تطوير "مخطّط الأشكال"

يوجد رمز المصدر لمصنع الحظر في العينات المحظورة المستودع في examples/developer-tools الدليل.

لإرسال تغيير إلى "أدوات المطوّرين" في نماذج Blockly، عليك اتّباع الخطوات المعتادة لتطوير نماذج Blockly. على عكس العمل مع الإضافات، عليك تشغيل npm install من دليل examples/developer-tools مباشرةً، وليس على مستوى الجذر في blockly-samples.

تثبيت المكوّن الإضافي

لكي يعرض "بلوغ فاكتوري" حقلك المخصص في المعاينة، إلى تثبيت الحقل المخصص. أضف الحقل الخاص بك كتبعية لـ npm أدوات مطوري البرامج. بعد ذلك، سجِّل النطاق أو نفِّذ أي عمل إعدادات آخر ضروري في developer-tools/src/blocks/index.ts.

إنشاء حظر للحقل

بما أنّ "مصنع المربّعات" يستخدم كتلاً لإنشاء مربّعات مخصّصة، ستحتاج إلى مربّع يمثل الحقل المخصص.

إنشاء تعريف حظر

تحتاج إلى تصميم قالب لحقلك؛ إذا أردت الحصول على علامة وصفية، يمكنك حتى من تصميمه باستخدام Block مصانع! يجب أن تسمح الكتلة للمستخدم بضبط الإعدادات المطلوبة لحقلك، مثل القيم التلقائية والاسم. إضافة هذا حظر التعريف على developer-tools/src/blocks/fields.ts واستيراده في developer-tools/src/blocks/index.ts

إضافة مربّع إلى مجموعة الأدوات

بعد ذلك، عليك إضافة هذا الرمز إلى تعريف مجموعة الأدوات لإتاحته للمستخدمين. يمكن العثور على تعريف صندوق الأدوات في developer-tools/src/toolbox.ts. من المفترض أن تتم إضافة العنصر إلى فئة "الحقول".

أدوات إنشاء الرموز

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

أنشئ ملفًا لوحدة الحقول في الدليل output-generators/fields. ستضيف إلى هذا الملف أدوات إنشاء الرموز البرمجية لكلّ من أدوات الإنشاء التالية. استيراد هذا الملف في ملف blocks/index.ts حتى تحميل دوال إنشاء رمز الكتلة في التطبيق.

تعريف JavaScript

ينشئ الرمز javascriptDefinitionGenerator الرمز الذي سيتم تضمينه في تعريف JavaScript لوحدة تتضمّن حقلك المخصّص. ويعني ذلك عادةً أنّ أداة إنشاء الرموز البرمجية للوحدات يجب أن تعرِض سطر رمز برمجيًا يبدو على النحو التالي: .appendField(new YourFieldConstructor(arg1, arg2), 'userSpecifiedName'). ملاحظة أن هذا السطر من الرمز لا يتضمن فاصلة منقوطة، لأن الإدخال الذي يحتوي على حقول متعددة، وسوف يتضمن العديد من المكالمات إلى appendField متسلسلة. يتم سحب الوسيطات في الدالة الإنشائية من القيم التي استخدمها المستخدم على كتلة الحقل. وفي ما يلي مثال على منشئ رمز الكتل هذا FieldAngle:

javascriptDefinitionGenerator.forBlock['field_angle'] = function (
  block: Blockly.Block,
  generator: JavascriptDefinitionGenerator,
): string {
  const name = generator.quote_(block.getFieldValue('FIELDNAME'));
  const angle = block.getFieldValue('ANGLE');
  return `.appendField(new FieldAngle(${angle}), ${name})`;
};

تحتوي كتلة الزاوية التي جرّها المستخدم من فئة "الحقول" في صندوق أدوات Block Factory على حقلَين:

  • FIELDNAME: يمكن للمستخدم ضبط اسم الحقل في الوحدة المخصّصة له
  • ANGLE: يمكن للمستخدم ضبط قيمة الزاوية التلقائية.

في أداة إنشاء الرموز البرمجية، نحصل على قيمة الزاوية التلقائية ونمررها كأحد المَعلمات الوحيدة للدالة الإنشائية FieldAngle. يتم دائمًا تمرير اسم الحقل كوسيطة ثانية إلى appendField.

تعريف JSON

تشبه jsonDefinitionGenerator، لكن هذا الجزء من JSON يستنِد إلى كتلة تعريف يتجاوب مع حقلك. وعادةً ما يكون هذا الرمز بتنسيق JSON يتضمن:

  • type: تتوافق مع اسم حقلك في سجلّ حقول Blockly
  • name: يمكن للمستخدم ضبط اسم الحقل في الوحدة الأساسية المخصّصة.
  • أي سمات مخصّصة أخرى تتطلّبها عملية إعداد ملف json في الحقل .

في ما يلي مثال من FieldAngle مرة أخرى:

jsonDefinitionGenerator.forBlock['field_angle'] = function (
  block: Blockly.Block,
  generator: JsonDefinitionGenerator,
): string {
  const code = {
    type: 'field_angle',
    name: block.getFieldValue('FIELDNAME'),
    angle: block.getFieldValue('ANGLE'),
  };
  return JSON.stringify(code);
};

عناوين الرموز

ينشئ "منشئ عنوان الرمز" إخراج "عناوين التعليمات البرمجية" المعروضة في القسم مصنع. يمكن تبديل هذا الإخراج بين عمليات استيراد esmodule وعلامات النصوص البرمجية، استنادًا إلى الطريقة التي يريد بها المستخدم تحميل الرمز، لذلك هناك في الواقع حالتان مختلفتان لإنشاء الرمز: حالة لكل حالة. عليك إضافة أداة إنشاء رمز برمجي لإنشاء رمز برمجي لكل منها. إليك مثال على FieldAngle:

importHeaderGenerator.forBlock['field_angle'] = function (
  block: Blockly.Block,
  generator: CodeHeaderGenerator,
): string {
  generator.addHeaderLine(
    `import {registerFieldAngle, FieldAngle} from '@blockly/field-angle';`,
  );
  generator.addHeaderLine(`registerFieldAngle();`);
  return '';
};

scriptHeaderGenerator.forBlock['field_angle'] = function (
  block: Blockly.Block,
  generator: CodeHeaderGenerator,
): string {
  generator.addHeaderLine(
    `<script src="https://unpkg.com/@blockly/field-angle"></script>`,
  );
  generator.addHeaderLine(`registerFieldAngle();`);
  return '';
};

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

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

مقتطف المولد

وأخيرًا، لدينا المنشئ الذي ينشئ كعب المنشئ للحقل. ضِمن منشئ أكواد الحظر هذا، ستكتب رمز ينشئ رمز المستخدم على كتابة التعليمة البرمجية التي تقوم بإنشاء التعليمات البرمجية. هل تشعر بالارتباك بعد؟ الأمر أسهل من ذلك أَصْوَاتْ

يتضمّن العنصر النائب لإنشاء النموذج الخاص بالحظر المخصّص متغيّرًا مُعدًّا مسبقًا يمثّل كل حقل في الحظر. بعد ذلك، هناك TODO يجب على المستخدم الانتهاء من تجميع كل هذه المتغيرات في سلسلة التعليمات البرمجية النهائية فستعود كتلة مخصصة. وهذا يعني عادةً أن كل برامج إنشاء رموز الحظر المطلوب تنفيذه هو إرجاع السطر الذي يُنشئ هذا المتغير المخصص. لنفترض أن المستخدم هو إنشاء كتلة مخصصة تضيف أشعة الشمس إلى اللوحة. هم أضف حقلاً زاوية إلى القطعة وقم بتسميته "SUN_DIRECTION". سيتضمّن الرمز البرمجي التمهيدي لإنشاء ملف تعريف الارتباط لهذه الكتلة السطر const angle_sun_direction = block.getFieldValue("SUN_DIRECTION");. هذا هو سطر الرمز البرمجي للحظر منشئ حقل الزاوية يحتاج إلى عرض:

generatorStubGenerator.forBlock['field_angle'] = function (
  block: Blockly.Block,
  generator: GeneratorStubGenerator,
): string {
  const name = block.getFieldValue('FIELDNAME');
  const fieldVar = generator.createVariableName('angle', name);
  return `const ${fieldVar} = block.getFieldValue(${generator.quote_(
    name,
  )});\n`;
};

للحصول على اسم موحّد للمتغيّر، يمكنك استدعاء generator.createVariableName وضبط نوع الحقل (مثل angle وnumber وما إلى ذلك) مع الاسم الذي أطلقه المستخدم على حقله.

اختبار الميزة

بعد كتابة جميع هذه الأجزاء، ينبغي أن تكون قادرًا على بدء المربع مصنع عن طريق تشغيل npm start في blockly-samples/examples/developer-tools الدليل. من المفترض أن تتمكّن من سحب العنصر من فئة الحقل وإضافته إلى إدخال في عنصر، ومشاهدة تغيُّر الإخراج. تحقق من أن معاينة الكتلة تبدو صحيحة، وأن التعليمات البرمجية لكل قسم من أقسام الإخراج صحيح.