يناقش هذا المستند كيفية إنشاء مكوّن إضافي جديد. على الرغم من أنّ العملية الموضّحة مخصّصة لإنشاء مكوّنات إضافية تابعة للطرف الأول، يمكنك استخدامها كإرشادات لإنشاء مكوّنات إضافية تابعة لجهات خارجية.
للحصول على نظرة عامة حول المكوّنات الإضافية، راجِع المكوّنات الإضافية.
للحصول على مقدّمة سريعة حول كيفية إنشاء مكوّن إضافي، يمكنك الاطّلاع على محاضرة حول كيفية إنشاء مكوّن إضافي (2021).
الطرف الأول مقابل الطرف الثالث
المستخدم المستهدف للمكوّن الإضافي هو مطوّر برامج يعثر على المكوّن الإضافي ويستخدمه من خلال npm.
تتوفّر مكوّنات إضافية خاصة بالطرف الأول يدعمها فريق Blockly ويتم نشرها ضمن النطاق @blockly على npm. وهي مصمَّمة لتكون قابلة للاستخدام في مجموعة واسعة من تطبيقات Blockly، كما أنّها ثابتة وسهلة الاستخدام. ويتم تخزينها في
blockly-samples. يمكن استخدام حقل لضبط سرعة المحرك في العديد من مشاريع الروبوتات، وهو خيار جيد لمكوّن إضافي تابع للجهة الأولى.
يتم الحفاظ على الإضافات الخارجية ونشرها بشكل مستقل. وقد تكون هذه الوحدات أكثر تعقيدًا أو تجريبية أو تستهدف نطاقًا أضيق من تطبيقات Blockly. من الأفضل أن يكون حقل تعديل عنصر معيّن محدّد بواسطة مخطط قاعدة البيانات عبارة عن إضافة تابعة لجهة خارجية.
معايير الطرف الأول
يجب أن تستوفي الإضافات التابعة للطرف الأول المتطلبات التالية:
- العمل على جميع الأنظمة الأساسية الرئيسية، ما لم يمنحك فريق Blockly إذنًا بالإعفاء.
- Chrome وFirefox وSafari وEdge
- أن يكون لديك مؤلف على استعداد للتعامل مع الأخطاء خلال السنة الأولى
- لا تستخدم أسلوب monkeypatch في 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 الأساسية. يتم نشر Core Blockly
في الأسبوع الأخير من كل ربع سنة (مرة كل ثلاثة أشهر).