قوائم السياقات

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

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

ملاحظة: اطّلِع على الدرس التطبيقي حول ترميز قائمة السياق للحصول على أمثلة عملية حول إضافة خيارات قائمة السياق.

تنفيذ خيار جديد

لتنفيذ خيار جديد لقائمة السياقات، يجب استيفاء واجهة RegistryItem.

رقم التعريف

يجب أن تكون السمة id سلسلة فريدة تشير إلى وظيفة خيار قائمة السياق.

const deleteOption = {
  id: 'deleteElement',
};

النطاق

تُعلِم السمة scopeType بشكل حظري بالسياق الذي قد يظهر فيه خيار القائمة والمعلومات التي يجب تمريرها إلى displayText وpreconditionFn وcallback. يمكن تحديد نطاق قوائم السياق على الكتل وتعليقات مساحة العمل ومساحات العمل.

const deleteOption = {
  scopeType: Blockly.ContextMenuRegistry.ScopeType.BLOCK,
};

إذا كنت تريد أن تعمل قائمة السياق في نطاقات متعددة، عليك تكرار خيار قائمة السياق وإعادة تحديد معلَمة النطاق لكل نطاق.

const otherDeleteOption = {...deleteOption};
otherDeleteOption.scopeType = Blockly.ContextMenuRegistry.ScopeType.COMMENT;

النص الذي يظهر للمستخدم

علامة displayText هي ما يجب عرضه للمستخدم كجزء من خيار القائمة. قد يكون النص المعروض سلسلة، أو HTML، أو دالة تعرض إما سلسلة أو HTML.

const deleteOption = {
  displayText: 'Delete block',
};

إذا كنت تريد عرض ترجمة من Blockly.Msg، عليك استخدام دالة. إذا حاولت تحديد القيمة مباشرةً، قد لا يتم تحميل الرسائل وستحصل على القيمة undefined بدلاً من ذلك.

const deleteOption = {
  displayText: () => Blockly.Msg['MY_DELETE_OPTION_TEXT'],
};

إذا كنت تستخدم دالة، يتم أيضًا تمرير القيمة Scope التي تتيح لك الوصول إلى العنصر المرتبط بقائمة السياق (مثل الكتلة أو مساحة العمل). يمكنك استخدام هذا لإضافة معلومات حول العنصر إلى النص المعروض.

const deleteOption = {
  displayText: (scope) => `Delete ${scope.block.type} block`,
}

الوزن

تحدّد weight ترتيب عرض العناصر في قائمة السياق. يتم عرض القيم الأكثر إيجابية في موضع أدنى في القائمة من القيم الأقل إيجابية. (يمكنك أن تتخيل أن الخيارات ذات الأوزان الأعلى "أثقل" بحيث تتجه إلى الأسفل.)

const deleteOption = {
  weight: 10;
}

تتزايد الترجيحات لخيارات قائمة السياق المضمنة بترتيب تصاعدي بدءًا من 1 وزيادتها بمقدار 1.

الشرط المُسبَق

بالإضافة إلى scopeType، يمكنك استخدام preconditionFn لفرض قيود على وقت وطريقة عرض خيار قائمة السياقات.

من المفترض أن يتم عرض واحدة من مجموعة من السلاسل: 'enabled' أو 'disabled' أو 'hidden'.

القيمة	الوصف	صورة
مفعّلة	تُظهر أن هذا الخيار نشط.
غير مفعّلة	يظهر أن الخيار غير نشط.
مخفي	وإخفاء الخيار.

يتم أيضًا تمرير preconditionFn إلى Scope التي يمكنك استخدامها لتحديد حالة الخيار.

const deleteOption = {
  preconditionFn: (scope) => {
    if (scope.block.isDeletable()) {
      return 'enabled';
    }
    return 'disabled';
  }
}

معاودة الاتصال

تنفِّذ السمة callback إجراء عنصر قائمة السياق. لقد اجتازت Scope وPointerEvent. وPointerEvent هو الحدث الأصلي الذي أدّى إلى فتح قائمة السياق، وليس الحدث الذي حدَّد خيارًا. يمكنك استخدام الحدث لمعرفة مكان حدوث النقرة. ويتيح لك هذا، على سبيل المثال، إنشاء مجموعة جديدة في الموقع الجغرافي للنقر.

const deleteOption = {
  callback: (scope, e) => {
    scope.block.dispose();
  }
}

تسجيل

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

const deleteOption = { /* implementations from above */ };
Blockly.ContextMenuRegistry.registry.register(deleteOption);

تعديل الخيارات لكل نوع من أنواع الحظر

تقدّم القوالب طريقة إضافية لتعديل قوائم السياق، وهي استخدام استبدال سمة customContextMenu بها. تستخدم هذه الطريقة مصفوفة من كائنات ContextMenuOption (التي يتم تجميعها من عناصر القائمة المسجَّلة) ثم تعدّل هذا الصفيف في المكان لتحديد المجموعة النهائية من الخيارات المعروضة.

لمزيد من المعلومات، يُرجى الاطّلاع على تحديد الوحدات الأساسية وقوائم السياق المخصّصة.

تحتوي مساحات العمل أيضًا على طريقة configureContextMenu والتي تعمل بالطريقة نفسها.

إزالة خيار

يمكنك إزالة خيار من قائمة السياقات عن طريق إلغاء تسجيله باستخدام رقم التعريف.

Blockly.ContextMenuRegistry.registry.unregister('someID');

تتوفّر أرقام تعريف الخيارات التلقائية في contextmenu_items.ts.

تعديل خيار

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

const option = Blockly.ContextMenuRegistry.registry.getItem('someID');
option?.displayText = 'some other display text';