يتناول هذا المستند كيفية إنشاء مكوّن إضافي جديد. على الرغم من أنّ العملية التي يصفها تهدف إلى إنشاء مكونات إضافية من الطرف الأول، يمكنك استخدامها كدليل لإنشاء مكونات إضافية تابعة لجهات خارجية.
للحصول على نظرة عامة على المكوّنات الإضافية، اطّلِع على المكوّنات الإضافية.
للحصول على مقدمة سريعة عن إنشاء مكوّن إضافي، يمكنك الاطّلاع على كيفية إنشاء مكوّن إضافي talk (2021).
الطرف الأول في مقابل الجهة الخارجية
المستخدم المستهدَف للمكوّنة الإضافية هو المطوّر الذي يعثر على المكوّنة الإضافية ويستخدمها من خلال npm.
يتيح فريق Blockly استخدام المكوّنات الإضافية التابعة للجهة الأولى، ويتم نشرها ضمن نطاق
@blockly على npm. تم تصميمها بحيث يمكن استخدامها في مجموعة كبيرة من
تطبيقات Blockly، وهي مستقرة وسهلة الاستخدام. ويتم تخزينها في ملف blockly-samples. يمكن استخدام حقل لتحديد سرعة المحرّك في العديد من مشاريع الروبوتات، وهو مرشح جيد لمكوّن إضافي تابع لجهة خارجية.
يتم الاحتفاظ بالمكونات الإضافية التابعة لجهات خارجية ونشرها بشكل مستقل. وقد تكون هذه التطبيقات أكثر تعقّدًا أو تجريبية أو مخصّصة لمجموعة أضيق من تطبيقات Blockly. إنّ الحقل لتعديل عنصر محدّد يحدّده مخطّط قاعدة بياناتك هو أفضل كإضافة تابعة لجهة خارجية.
معايير الطرف الأول
يجب أن تستوفي الإضافات التابعة للجهات الخارجية المتطلبات التالية:
- أن تعمل على جميع الأنظمة الأساسية الرئيسية، ما لم يمنح فريق Blocklyexemption
- Chrome وFirefox وSafari وEdge
- أن يكون لديك مؤلف على استعداد للتعامل مع الأخطاء في السنة الأولى
- لا تُعدِّل Blockly.
- أن تتضمّن واجهة برمجة تطبيقات محدّدة بوضوح وموثّقة
- لا تستدعي الدوال الخاصة أو الدوال الخاصة بالحِزم من نواة Blockly، ما لم يمنحَك فريق Blockly
إذنًا بذلك.
- يُسمح بإلغاء دوال الحِزم في فئة فرعية تحدّدها.
- إذا أردت الحصول على إعفاء، يُرجى طلب ذلك في مشكلة على blockly-samples.
- أن تتضمّن اختبارات
العملية
تمرّ المكونات الإضافية بأربع مراحل: الاقتراح، المناقشة، التنفيذ، النشر.
اقتراح
يبدأ المكوّن الإضافي كاقتراح. يمكنك اقتراح مكوّن إضافي من خلال إنشاء ملف شخصي جديد باستخدام نموذج طلب ميزة.
اطّلِع على كيفية كتابة طلب ميزة.
بالإضافة إلى المعلومات الأساسية لطلب الميزة، يجب أن يحتوي اقتراح المكوّن الإضافي على ما يلي:
- واجهة برمجة التطبيقات التي سيعرِضها المكوّن الإضافي
- واجهات برمجة التطبيقات التي يجب إضافتها أو تغييرها في Blockly الأساسية لتتوافق مع المكوّن الإضافي
- لقطات شاشة أو صور GIF أو نماذج تجريبية إذا كان المكوّن الإضافي يتضمّن ميزات واجهة مستخدِم
- شرح لسبب ضرورة أن يكون المكوّن الإضافي تابعًا للجهة المصنّعة للتطبيق بدلاً من مكوّن إضافي تابع لجهة خارجية
يراجع فريق Blockly الاقتراحات فور تلقّيها، ويغلق المشكلة أو يوافق على أنّه سيكون مكوّنًا إضافيًا جيدًا من إنشاء الطرف الأول.
مناقشة
بعد ذلك، ينتقل المكوّن الإضافي إلى مرحلة المناقشة. تشمل هذه المرحلة ما يلي:
- توضيح الوظيفة المطلوبة
- توضيح بشأن واجهة برمجة التطبيقات للمكوّن الإضافي
- التخطيط لتنفيذ الحملة
- التخطيط للاختبارات
- مناقشة التغييرات في واجهة برمجة التطبيقات في Blockly الأساسية
- تقسيم المكوّنات الإضافية الكبيرة إلى خطوات تنفيذ
- تسمية المكوّن الإضافي، استنادًا إلى اصطلاحات التسمية
- تأكيد استيفاء جميع معايير الطرف الأول
تحدث هذه المناقشة بشكل عام في مشكلة GitHub. كلما كان نطاق المكونات الإضافية محدودًا، كان بإمكانك إنهاء مرحلة المناقشة بشكل أسرع. قد تجذب المكونات الإضافية الأكبر حجمًا انتباه المنتدى وآراء قوية حول الحلّ المناسب. إذا حدث ذلك في مشكلتك، نبارك لك. لقد عثرت على موضوع يهتم به المستخدمون.
والهدف هو أن يتم في نهاية مرحلة المناقشة اتخاذ جميع قرارات التصميم الرئيسية وإعداد قائمة واضحة بخطوات التنفيذ. يجب تسجيل كلاهما في التعليقات على المشكلة.
أثناء المناقشة، قد نقرر أنّ المكوّن الإضافي يجب أن يكون مكوّنًا إضافيًا تابعًا لجهة خارجية،
وألّا يتم نشره ضمن نطاق @blockly. في هذه الحالة، سنشرح
سبب ذلك ونغلق المشكلة.
عند اكتمال المناقشة، يشير أحد أعضاء فريق Blockly إلى أنّه جاهز للتطبيق.
التنفيذ
تشمل خطوات التنفيذ ما يلي:
- تشغيل
npx @blockly/create-packageلإعداد المكوّن الإضافي ودليله من نموذج مزيد من المعلومات... - تنفيذ المنطق الأساسي للمكوّن الإضافي
- تنفيذ واجهة مستخدم، إذا لزم الأمر
- اختبار المكوّن الإضافي باستخدام Mocha
- توثيق المكوّن الإضافي، بما في ذلك
README
إذا تمت الموافقة على استخدام مكوّن إضافي مقترَح وكنت تريد العمل عليه، يمكنك التعليق على المشكلة وسؤال الفريق ما إذا كان المكوّن الإضافي لا يزال متاحًا للمساهمة.
يمكن أن يتم التنفيذ من قِبل عدة مساهمين بشكل موازٍ. يمكنك تنفيذ مكوّن إضافي بشكل تعاوني على نسختك المشتقة، أو من خلال طلبات سحب ضد هذا المستودع. إذا أردت التعاون في إنشاء مكوّن إضافي في هذا المستودع، اطلب من فريق Blockly إنشاء فرع ميزات لك.
يجب إضافة المكوّنات الإضافية إلى ملف
gh-pages/index.md
في فرع master من blockly-samples. سيؤدي ذلك إلى ظهورها
على موقع "مكوّنات إضافية" الإلكتروني. يجب أن تشير المكوّنات الإضافية
التابعة للطرف الأول إلى صفحة الاختبار. يمكن أيضًا إضافة مكونات إضافية تابعة لجهات خارجية
إلى هذه الصفحة، ويمكن أن تشير إلى رابط من اختيار مالكها، مثل
إصدار تجريبي مستضاف أو صفحة npm.
النشر
أخيرًا، النشر يستخدم فريق Blockly أداة Lerna لمحاولة إدارة الإصدارات والنشر لجميع الإضافات.
يتم كل يوم خميس نشر أيّ إضافات تمّ تغييرها منذ آخر إصدار لها. إذا كنت بحاجة إلى نشر تغيير في وقت أقرب، يُرجى الإشارة إلى ذلك في طلب الدمج.
يتم أيضًا تعديل موقع "المكوّنات الإضافية" الإلكتروني عند نشر المكوّنات الإضافية.
يجب وضع علامة private على المكوّنات الإضافية غير الجاهزة للنشر في
package.json. قد يحدث ذلك إذا كان المكوّن الإضافي يعتمد على تغيير لم يتم نشره بعد
في الإصدار الأساسي من Blockly. يتم نشر إصدار Blockly الأساسي
في الأسبوع الأخير من كل ربع سنة (مرة كل ثلاثة أشهر).