استخدام واجهات برمجة التطبيقات المحظورة

مقدمة

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

التصنيف الفرعي والتمديد

توجد نماذج متعددة لإضافة الوظائف في Blockly، بما في ذلك:

  • الفئات الفرعية (مثل إنشاء عارض جديد)
  • العناصر المركّبة (مثل إدراج إضافة حظر أو مغيّر)
  • تعريفات الحظر (مثل تعريفات حظر الإجراءات)

لأغراض هذه الوثيقة، تساوي الحالات الثلاث جميعها تصنيف فرعي.

إدخال فئات فرعية

نتيح استبدال فئات معيّنة من خلال طريقة Blockly.inject. هذه أن تُوسع الفئات الفرعية الفئة الأساسية أو أن تنفذ فئاتها من واجهة pyplot.

يمكنك تمرير الفئة الفرعية إلى طريقة الإدخال.

Blockly.inject('blocklyDiv', {
  plugins: {
    'metricsManager': CustomMetricsManagerClass
  }
}

أو يمكنك تسجيل صفك باستخدام "Blockly.registry" واستخدام اسم السجل لإدخال الفئة. يكون هذا مفيدًا في حالة تخزين الحقن الأخرى بتنسيق JSON نقي.

Blockly.registry.register(Blockly.registry.Type.METRICS_MANAGER, 'YOUR_NAME', SubClass);

Blockly.inject('blocklyDiv', {
  plugins: {
    'metricsManager': 'YOUR_NAME'
  }
}

يمكن استبدال الفئات التالية:

اسم التسجيل الفئة الأساسية/الواجهة
blockDragger Blockly.IBlockDragger
connectionChecker Blockly.IConnectionChecker
connectionPreviewer Blockly.IConnectionPreviewer
flyoutsVerticalToolbox Blockly.IFlyout
flyoutsHorizontalToolbox Blockly.IFlyout
metricsManager Blockly.IMetricsManager
renderer Blockly.blockRendering.Renderer
toolbox Blockly.IToolbox

للحصول على مزيد من المعلومات حول استخدام الواجهات، راجع قسم الواجهات الوثائق.

مستوى الرؤية

نستخدم معدِّلات وصول TypeScript لوضع علامة على إذن الوصول في المكتبة الأساسية على أنّه public أو private أو protected. قد تتم إضافة تعليقات توضيحية إلى بعض السمات باستخدام @internal في تعليقات TsDoc.

يتم توثيق كل السمتَين public وprotected في قسم المراجع في موقع Blockly الإلكتروني. يمكنك أيضًا تحقق من مستوى الرؤية من خلال قراءة الرمز.

عام

جميع العناصر التي يتم وضع علامة public عليها هي جزء من واجهة برمجة التطبيقات العامة الخاصة بنا. أي خاصية في وحدة إذا كان لا يحتوي على معدِّل مستوى الرؤية يعتبر عامًا.

نحاول عدم تغيير واجهة برمجة التطبيقات العامة بشكل متكرر أو بدون سبب وجيه، تحذير. ولكن الاستثناء هو أن نجعل واجهة برمجة تطبيقات جديدة متاحة للجميع في إصدار واحد، وتعديله في الإصدار التالي استجابةً للملاحظات المبكرة. بعد ذلك يمكنك تعتبر وظيفة عامة أو استقرار الملكية.

يمكن استدعاء الوظائف العامة من أي مكان، ويتم تجاوزها في الفئات الفرعية باعتبارها طالما أن التوقيع لا يتغير.

محمي

لا يمكن الوصول إلى الدوال والخصائص المحمية إلا عن طريق الفئة أو فئة فرعية.

يُسمَح للفئات الفرعية بتجاهل الدوال والخصائص المحمية، بدون تغيير توقيعات النوع.

على سبيل المثال، يمكن لعارض مخصَّص يعمل على توسيع فئة العارض الأساسي الوصول إلى وخصائصها المحمية.

في كل حالة، يجب أن تتأكد من فهمك لكيفية ترتيب الدالة أو الخاصية المستخدم في باقي التعليمات البرمجية.

خاص

ولا يمكن الوصول إليها إلا باستخدام رمز في ملف التعريف نفسه. مباشرةً الوصول إلى هذه الخصائص قد يؤدي إلى سلوك غير محدد.

لا يُسمح للفئات الفرعية بتجاوز الدوال والخصائص الخاصة.

تخضع المواقع الخاصة للتغيير بدون تحذير، إذ إنّها غير متاحة. تعتبر جزءًا من واجهة برمجة تطبيقات Blockly العامة.

لا تحتوي بعض الدوال في Blockly على تعليقات توضيحية حول مستوى الرؤية لأنّها لم يتم تصديرها من وحدتها. هذه الدوال هي في الأساس متغيرات محلية ولا يمكن استخدامها خارج الوحدة المحددة لها. يجب أخذهم في الاعتبار مماثلة للممتلكات الخاصة.

داخلي

الغرض من الدوال الداخلية والخصائص الداخلية هو استخدامها في المكتبة ولكن ليس خارجيًا. تم تحديدها من خلال TsDoc @internal التعليق التوضيحي.

تخضع الخصائص الداخلية للتغيير بدون تحذير، حيث لا يتم تعتبر جزءًا من واجهة برمجة تطبيقات Blockly العامة.

يمكن الوصول إلى المواقع الداخلية من أي مكان داخل النظام الأساسي، ويتم إلغاؤها في أي فئة فرعية في الأساس طالما أن التوقيع لا يتغير. يجب ألا تكون يتم الوصول إليها من خارج المكتبة الأساسية.

متوقفة نهائيًا

ولا يجب استخدام أي عناصر تم وضع علامة @deprecated عليها. تتضمن معظم عمليات الإيقاف على الرمز المفضل، إما في تحذير وحدة التحكم أو TSDoc.

حيثما أمكن، ستسجِّل الدوال التي تم إيقافها نهائيًا تحذيرًا يتضمن تاريخ الحذف المحدد واقتراح لدالة بديلة لطلبها.

الأسئلة الشائعة

ماذا لو كانت الدالة التي أريد استخدامها غير عامة؟

تقديم طلب ميزة على مجموعة Blockly الأساسية. قم بتضمين وصف لحالة الاستخدام الخاصة بك وبيانًا لما الذي تريد منا جعله عامًا.

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

وإذا قرّرنا إتاحة الفيديو للعلن، عليك أنت أو فريق Blockly التغيير المناسب، وسيتم نشره في إصدار Blockly التالي.

إذا اخترت استخدام عضو غير متاح للجميع في مكون إضافي، فيمكنك وضع علامة على كمكوّن تجريبي كإصدار تجريبي، وضمِّن المعلومات في README.

ماذا عن تصحيح القرود؟

اطّلِع على المزيد حول monkeypatching.

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

هل يمكنني إلغاء الوظائف العامة؟

عند التصنيف الفرعي: نعم. وبخلاف ذلك: لا، هذا منشور على شكل قرود.

هل يمكنني إلغاء الدوال المحمية؟

عند التصنيف الفرعي: نعم. وبخلاف ذلك: لا، هذا منشور على شكل قرود.

هل يمكنني إلغاء الدوال الداخلية أو الخاصة؟

لا، هذه ضربة للقرود.

متى يمكنني الوصول إلى المواقع مباشرةً؟ متى يجب أن أستخدم موجهًا أو ساعِدًا؟

إذا نشرنا أمرًا الحصول على أو دالة setter، يُرجى استخدامها بدلاً من للدخول إلى الموقع. إذا لم يكن العقار متاحًا للجميع، احرص على استخدام مفاتيح التبديل. والسكان.

ماذا لو لم يكن الموقع الإلكتروني يتضمّن تعليقًا توضيحيًا؟

بشكل افتراضي يكون عامًا، ولكن يرجى مراسلتنا في حالة ما إذا أردنا وضع زوج الضمائر/التعيين من أجلك.

ماذا لو لم تكن الدالة تتضمن تعليقًا توضيحيًا؟

ويكون علنيًا بشكل تلقائي.

ماذا لو لم أكن متأكدًا بعد؟

يمكنك طرح سؤال في المنتدى. وسنردّ عليك خلال يوم عمل بشكل عام.