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

مقدمة

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

الفئات الفرعية والتوسيع

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

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

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

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

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

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

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 في قسم المراجع ضمن موقع Bluely الإلكتروني. يمكنك أيضًا التحقق من مستوى الرؤية عن طريق قراءة التعليمات البرمجية.

علني

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

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

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

محمي

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

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

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

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

private

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

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

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

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

داخلي

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

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

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

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

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

حيثما أمكن، ستسجِّل الدوال المتوقفة تحذيرًا يتضمّن تاريخ الحذف المقصود واقتراحًا لاستدعاء دالة بديلة.

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

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

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

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

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

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

ماذا عن رياضة القرد؟

يمكنك الاطّلاع على مزيد من المعلومات حول قرد التصحيح.

يعتبر Monkeypatch (تطبيق Monkeycating) غير آمن لأن التصحيحات قد تتوقف عن العمل بدون إشعار بسبب استخدام أجزاء غير عامة من واجهة برمجة تطبيقات حظر. ويُعد التصحيح على أحد المكونات الإضافية أمرًا خطيرًا على وجه الخصوص، لأن التعليمات البرمجية الخاصة بك قد تتفاعل بشكل سيء مع أي مكون إضافي آخر ينفِّذ الرمز البرمجي نفسه. لهذا السبب، نقترح بشدّة عدم استخدام قرد لتصحيح الأخطاء في التطبيقات والمكونات الإضافية التابعة لجهات خارجية، ولن نقبل هذا الإجراء في المكوّنات الإضافية الخاصة بالطرف الأول.

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

عند التصنيف الفرعي: نعم. وإلا، فهذا يعني تنقيح القرود.

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

عند التصنيف الفرعي: نعم. وإلا، فهذا يعني تنقيح القرود.

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

لا، هذا هو تنسيق القرد.

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

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

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

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

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

تكون متاحة للجميع بشكل تلقائي.

ماذا أفعل إذا كنت لا أزال غير متأكّد؟

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