توضّح هذه الصفحة أفضل الممارسات لاستدعاء الدوالّ والوصول إلى السمات في Blockly الأساسية. تنطبق هذه المبادئ على إنشاء مكوّنات إضافية لخدمة Blockly وعلى دمج Blockly في تطبيق مستقل.
مستوى الرؤية
نستخدم مُعدِّلات الوصول
في TypeScript
لتحديد مستوى العرض في المكتبة الأساسية على أنّه public أو private أو protected.
قد يتمّ وضع تعليق توضيحي على بعض السمات باستخدام الرمز @internal في ملف TsDoc.
يتم توثيق جميع سمات public وprotected في قسم
المراجع على الموقع الإلكتروني لتطبيق Blockly. يمكنك أيضًا
التحقّق من مستوى العرض من خلال قراءة الرمز.
عام
إنّ أي عنصر تم وضع علامة public عليه هو جزء من واجهة برمجة التطبيقات المتاحة للجميع. يُعتبر أيّ سمة في وحدة
لا تتضمّن مُعدِّل مستوى العرض علنية.
نحاول عدم تغيير واجهة برمجة التطبيقات المتاحة للجميع بشكل متكرّر أو بدون سبب وجيه وبدون إعلام مسبق. الاستثناء: قد نُطلق واجهة برمجة تطبيقات جديدة للجميع في إصدار واحد ونعدِّلها في الإصدار التالي استجابةً للملاحظات المُرسَلة في وقت مبكر. بعد ذلك، يمكنك اعتبار الدالة أو الموقع العامَين ثابتَين.
يمكن استدعاء الدوال العامة من أي مكان، ويمكن إلغاء تنفيذها في الفئات الفرعية ما دام التوقيع لم يتغيّر.
محمي
لا يمكن الوصول إلى الدوالّ والسمات المحمية إلا من خلال الفئة المحدّدة أو فئة فرعية.
يُسمح للطبقات الفرعية بتجاهل الدوال والخصائص المحمية، بدون تغيير توقيعات الأنواع.
على سبيل المثال، يمكن لبرنامج عرض مخصّص ينشئ فئة برنامج عرض أساسية الوصول إلى خصائصه المحمية.
في كل حالة، يجب التأكّد من فهم كيفية استخدام الدالة أو السمة في بقية الرمز.
خاص
ولا يمكن الوصول إليها إلا من خلال رمز في الملف نفسه الذي يحتوي على التعريف. وقد يؤدي الوصول إلى هذه السمات مباشرةً إلى سلوك غير محدّد.
لا يُسمح للطبقات الفرعية بإلغاء الوظائف والخصائص الخاصة.
تخضع المواقع الخاصة للتغيير بدون تحذير، لأنّها لا تُعدّ جزءًا من واجهة برمجة التطبيقات العامة في Blockly.
لا تحتوي بعض الدوالّ في Blockly على تعليقات توضيحية للظهور لأنّه لا يتم تصديرها من وحدتها. هذه الدوالّ هي في الأساس متغيّرات محلية ولا يمكن استخدامها خارج الوحدة المحدّدة لها. ويجب اعتبارها مكافئة للمواقع الخاصة.
داخلي
فالدوالّ والسمات الداخلية مخصّصة للاستخدام داخل مكتبة
الأساسية، وليس خارجيًا. ويتم تحديدها باستخدام التعليق التوضيحي @internal
TsDoc.
تخضع المواقع الداخلية للتغيير بدون تحذير، لأنّها لا تُعدّ جزءًا من واجهة برمجة التطبيقات العامة في Blockly.
يمكن الوصول إلى السمات الداخلية من أي مكان في التطبيق الأساسي، ويمكن إلغاؤها في الفئات الفرعية في التطبيق الأساسي ما دامت التوقيعات لم تتغيّر. يجب عدم الوصول إليها من خارج المكتبة الأساسية.
متوقفة نهائيًا
يجب عدم استخدام أي محتوى تم وضع علامة @deprecated عليه. تتضمّن معظم عمليات الإيقاف نهائيًا
إرشادات حول الرمز المفضّل، إما في تحذير وحدة التحكّم أو TSDoc.
ستسجِّل الدوالّ المتوقّفة نهائيًا تحذيرًا يتضمن تاريخ الحذف المقصود واقتراحًا لدالة بديلة يمكن استدعاؤها، وذلك كلما أمكن.
الأسئلة الشائعة
في ما يلي بعض الأسئلة الشائعة التي واجهها فريق Blockly.
ماذا لو لم تكن الدالة التي أريد استخدامها علنية؟
قدِّم طلبًا لإضافة ميزة في Blockly الأساسية. يُرجى تضمين وصف لحالة الاستخدام وبيان عما يلي: المعلومات التي تريد أن ننشرها.
سنستخدم هذه الميزة لطلب مناقشة ما إذا كان سيتم نشرها علنًا أو ما إذا كانت هناك طرق أخرى للحصول على المعلومات نفسها.
إذا قرّرنا نشرها، سيصبح بإمكانك أو بإمكان فريق Blockly إجراء ال تغيير المناسب، وسيتم نشرها في الإصدار التالي من Blockly.
إذا اخترت استخدام عضو غير علني في مكوّن إضافي، ننصحك بوضع علامة على
المكوّن الإضافي كإصدار تجريبي وتضمين المعلومات في README.
ماذا عن التصحيح البرمجي؟
اطّلِع على مزيد من المعلومات حول تعديل الرمز البرمجي.
إنّ استخدام أسلوب "تصحيح الأخطاء البرمجية" غير آمن، لأنّه قد يتوقّف عن العمل بدون إشعار بسبب استخدام أجزاء غير علنية من واجهة برمجة التطبيقات Blockly API. إنّ تصحيح الأخطاء في المكوّن الإضافي هو إجراء خطير بشكل خاص، لأنّ الرمز البرمجي قد يتفاعل بشكلٍ سيئ مع أي مكوّن إضافي آخر يُجري تصحيحًا برمجيًا للرمز نفسه. لهذا السبب، ننصح بشدّة بعدم استخدام تقنية تعديل الرمز البرمجي في التطبيقات والمكوّنات الإضافية التابعة لجهات خارجية، ولن نقبل استخدامها في المكوّنات الإضافية التابعة للجهة المصنّعة.
هل يمكنني إلغاء الدوال العامة؟
عند إنشاء فئة فرعية: نعم. بخلاف ذلك: لا، هذا يُعدّ تعديلاً عشوائيًا.
هل يمكنني إلغاء الوظائف المحمية؟
عند إنشاء فئة فرعية: نعم. بخلاف ذلك: لا، هذا يُعدّ تعديلاً عشوائيًا.
هل يمكنني إلغاء الدوال الداخلية أو الخاصة؟
لا، هذا يُعرف باسم "تصحيح الأخطاء البرمجية".
متى يمكنني الوصول إلى المواقع مباشرةً؟ متى يجب استخدام طريقة getter أو طريقة setter؟
إذا نشرنا دالة الحصول أو الضبط، يُرجى استخدامها بدلاً من الوصول إلى السمة مباشرةً. إذا لم تكن السمة علنية، استخدِم بالتأكيد وظائف الالتقاط والتعديل.
ماذا لو لم يكن للموقع تعليق توضيحي؟
تكون هذه القيمة علنية تلقائيًا، ولكن يُرجى مراسلتنا إذا أردنا استخدام أسلوبين للحصول على القيمة وضبطها.
ماذا لو لم تتضمّن الدالة تعليقًا توضيحيًا؟
ويكون هذا الخيار متاحًا للجميع بشكل تلقائي.
ماذا لو لم أكن متأكّدًا بعد؟
يمكنك طرح سؤال في المنتدى وسنردّ عليك في غضون بضعة أيام.