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

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

تطوير في مصنع البلك

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

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

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

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

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

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

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

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

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

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

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

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

أنشِئ ملفًا لمجموعة الحقول في الدليل 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})`;
};

تحتوي كتلة الزوايا التي سحبها المستخدم من فئة "الحقول" في مربع أدوات كتلة الإعدادات على حقلين:

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);
};

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

ينشئ "منشئ عنوان الرمز" مخرجات عناوين التعليمات البرمجية التي تظهر في "Block Machine". ويمكن التبديل بين عمليات استيراد الوحدة وعلامات النصوص البرمجية، وفقًا للطريقة التي يرغب المستخدم في تحميل الرمز البرمجي من خلالها، لذلك هناك في الواقع مثيلان مختلفان للمنشئ: أحدهما لكل حالة. تحتاج إلى إضافة منشئ كود حظر لكل منها. إليك مثال على 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. يُفترض أن تكون قادرًا على سحب الكتلة من فئة الحقل وإضافتها إلى مدخل على كتلة، ومشاهدة تغيير الإخراج. تحقق من أن معاينة الكتلة تبدو صحيحة، وأن التعليمات البرمجية لكل قسم من أقسام الإخراج صحيحة.