chrome.contextMenus

الوصف

استخدِم واجهة برمجة التطبيقات chrome.contextMenus لإضافة عناصر إلى قائمة سياقات Google Chrome. يمكنك اختيار أنواع العناصر التي تنطبق عليها إضافات قائمة السياق، مثل الصور والروابط التشعّبية والصفحات.

الأذونات

contextMenus

يجب الإفصاح عن إذن ""contextMenus"" في ملف بيان الإضافة لاستخدام واجهة برمجة التطبيقات. كذلك، يجب تحديد رمز بحجم 16 × 16 بكسل للعرض بجانب عنصر القائمة. على سبيل المثال:

{
  "name": "My extension",
  ...
  "permissions": [
    "contextMenus"
  ],
  "icons": {
    "16": "icon-bitty.png",
    "48": "icon-small.png",
    "128": "icon-large.png"
  },
  ...
}

المفاهيم والاستخدام

يمكن أن تظهر عناصر قائمة السياقات في أي مستند (أو إطار داخل مستند)، حتى العناصر التي تحتوي على file:// أو chrome:// URL. للتحكم في المستندات التي يمكن أن تظهر عناصرك فيها، حدد الحقل documentUrlPatterns عند استدعاء طريقة create() أو update().

يمكنك إنشاء أي عدد تريده من عناصر قائمة السياقات، ولكن إذا كان هناك أكثر من عنصر من الإضافة مرئية في وقت واحد، يعمل Google Chrome تلقائيًا على تصغيرها إلى قائمة رئيسية واحدة.

أمثلة

لتجربة واجهة برمجة التطبيقات هذه، يمكنك تثبيت مثال على واجهة برمجة التطبيقات context menus من chrome-extension-samples المستودع.

الأنواع

ContextType

الإصدار 44 من Chrome أو الإصدارات الأحدث

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

Enum

"الكل"

"الصفحة"

"الإطار"

"الاختيار"

"الرابط"

"تعديل"

"صورة"

"الفيديو"

"audio"

"مشغّل التطبيقات"

"browser_action"

"page_action"

الإجراء

CreateProperties

الإصدار 123 من Chrome أو الإصدارات الأحدث

خصائص عنصر قائمة السياقات الجديد

أماكن إقامة

  • تم التحديد

    قيمة منطقية اختيارية

    الحالة الأولية لمربّع الاختيار أو زر الاختيار: true للنوع المحدّد، والقيمة false غير محدَّدة. يمكن تحديد زر اختيار واحد فقط في كل مرة في مجموعة معينة.

  • السياقات

    [ContextType, ...ContextType[]] اختياري

    قائمة السياقات التي سيظهر فيها هذا العنصر في القائمة وتكون القيمة التلقائية هي ['page'].

  • documentUrlPatterns

    string[] اختيارية

    لتقييد تطبيق العنصر فقط على المستندات أو الإطارات التي يتطابق عنوان URL لها مع أحد الأنماط المحدّدة. لمعرفة تفاصيل حول تنسيقات الأنماط، يُرجى الاطّلاع على أنماط المطابقة.

  • مفعّلة

    قيمة منطقية اختيارية

    تحدّد هذه السمة ما إذا كان عنصر قائمة السياقات مفعَّلاً أو غير مفعَّل. وتكون القيمة التلقائية هي true.

  • id

    سلسلة اختيارية

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

  • parentId

    string | الرقم اختياري

    رقم تعريف عنصر قائمة رئيسي يؤدي ذلك إلى جعل العنصر ثانويًا لعنصر تمت إضافته مسبقًا.

  • targetUrlPatterns

    string[] اختيارية

    مثل documentUrlPatterns، الفلاتر المستندة إلى السمة src في العلامات img وaudio وvideo والسمة href لعلامات a.

  • title

    سلسلة اختيارية

    النص الذي سيتم عرضه في العنصر تكون هذه القيمة مطلوبة ما لم تكن قيمة السمة type هي separator. عندما يكون السياق selection، استخدِم %s ضمن السلسلة لعرض النص المحدَّد. على سبيل المثال، إذا كانت قيمة هذه المعلمة هي "ترجمة '%s' إلى Pig Latin" ويختار المستخدم كلمة "رائع"، يكون عنصر قائمة السياق لتحديده هو "ترجمة "رائع" إلى Pig Latin".

  • كتابة

    ItemType اختياري

    نوع عنصر القائمة. وتكون القيمة التلقائية هي normal.

  • مرئي

    قيمة منطقية اختيارية

    ما إذا كان العنصر مرئيًا في القائمة

  • onclick

    null اختياري

    دالة يتم استدعاءها عند النقر فوق عنصر القائمة. ولا يتوفّر ذلك داخل مشغّل الخدمات. بدلاً من ذلك، يجب تسجيل مستمع إلى contextMenus.onClicked.

    تبدو دالة onclick كما يلي: 

    (info: OnClickData, tab: Tab) => {...}

    • معلومات

      OnClickData

      معلومات حول السلعة التي تم النقر عليها والسياق الذي حدثت فيه النقرة

    • تفاصيل علامة التبويب التي حدثت فيها النقرة. هذه المعلمة غير متوفرة لتطبيقات النظام الأساسي.

ItemType

الإصدار 44 من Chrome أو الإصدارات الأحدث

نوع عنصر القائمة.

Enum

"عادي"

"مربّع الاختيار"

"راديو"

"الفاصل"

OnClickData

المعلومات التي يتم إرسالها عند النقر على عنصر في قائمة السياقات

أماكن إقامة

  • تم التحديد

    قيمة منطقية اختيارية

    علامة تشير إلى حالة مربّع اختيار أو عنصر اختيار بعد النقر عليه.

  • قابل للتعديل

    منطقي

    علامة تشير إلى ما إذا كان العنصر قابلاً للتعديل (إدخال النص أو مساحة النص أو غير ذلك)

  • frameId

    الرقم اختياري

    الإصدار 51 من Chrome أو الإصدارات الأحدث

    رقم تعريف الإطار الخاص بالعنصر الذي تم النقر على قائمة السياقات فيه، إذا كان في إطار.

  • frameUrl

    سلسلة اختيارية

    تمثّل هذه السمة عنوان URL لإطار العنصر الذي تم النقر على قائمة السياقات فيه، إذا كان في إطار.

  • linkUrl

    سلسلة اختيارية

    إذا كان العنصر عبارة عن رابط، فهذا يعني عنوان URL الذي يشير إليه.

  • mediaType

    سلسلة اختيارية

    أحد الخيارات "صورة" أو "فيديو" أو "صوت" إذا تم تفعيل قائمة السياق على أحد هذه الأنواع من العناصر.

  • menuItemId

    string | الرقم

    رقم تعريف العنصر في القائمة الذي تم النقر عليه.

  • pageUrl

    سلسلة اختيارية

    عنوان URL للصفحة التي تم النقر فيها على عنصر القائمة. لا يتم ضبط هذه السمة في حال حدوث النقرة في سياق لا تتوفّر فيه صفحة حالية، مثلاً في قائمة سياقات مشغّل التطبيقات.

  • parentMenuItemId

    string | الرقم اختياري

    رقم التعريف الرئيسي، إن توفّر، للسلعة التي تم النقر عليها.

  • selectionText

    سلسلة اختيارية

    تمثّل هذه السمة النص الخاص بتحديد السياق، إن توفّر.

  • srcUrl

    سلسلة اختيارية

    ستكون متوفّرة للعناصر التي تحتوي على "src" عنوان URL.

  • wasChecked

    قيمة منطقية اختيارية

    علامة تشير إلى حالة مربّع الاختيار أو عنصر الاختيار قبل النقر عليه.

أماكن إقامة

ACTION_MENU_TOP_LEVEL_LIMIT

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

القيمة

6

الطُرق

create()

chrome.contextMenus.create(
  createProperties: CreateProperties,
  callback?: function,
)

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

المعلمات

  • createProperties

    CreateProperties

  • رد الاتصال

    الدالة اختيارية

    تظهر المَعلمة callback على النحو التالي: 

    () => void

المرتجعات

  • الرقم | سلسلة

    رقم تعريف العنصر الذي تم إنشاؤه حديثًا.

remove()

وعود 
chrome.contextMenus.remove(
  menuItemId: string | number,
  callback?: function,
)

يزيل عنصر قائمة السياقات.

المعلمات

  • menuItemId

    string | الرقم

    رقم تعريف عنصر قائمة السياق المطلوب إزالته.

  • رد الاتصال

    الدالة اختيارية

    تظهر المَعلمة callback على النحو التالي: 

    () => void

المرتجعات

  • وعود <باطلة>

    الإصدار 123 من Chrome أو الإصدارات الأحدث

    تتوفّر الوعود في الإصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير معاودة الاتصال. التوافق مع الأنظمة القديمة. لا يمكنك استخدام كلتيهما في نفس استدعاء الدالة. تشير رسالة الأشكال البيانية يتم حل الوعد بنفس النوع الذي يتم إرساله إلى معاودة الاتصال.

removeAll()

وعود 
chrome.contextMenus.removeAll(
  callback?: function,
)

يزيل جميع عناصر قائمة السياقات التي أضافتها هذه الإضافة.

المعلمات

  • رد الاتصال

    الدالة اختيارية

    تظهر المَعلمة callback على النحو التالي: 

    () => void

المرتجعات

  • وعود <باطلة>

    الإصدار 123 من Chrome أو الإصدارات الأحدث

    تتوفّر الوعود في الإصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير معاودة الاتصال. التوافق مع الأنظمة القديمة. لا يمكنك استخدام كلتيهما في نفس استدعاء الدالة. تشير رسالة الأشكال البيانية يتم حل الوعد بنفس النوع الذي يتم إرساله إلى معاودة الاتصال.

update()

وعود 
chrome.contextMenus.update(
  id: string | number,
  updateProperties: object,
  callback?: function,
)

يؤدي هذا الإجراء إلى تعديل عنصر في قائمة السياقات تم إنشاؤه سابقًا.

المعلمات

  • id

    string | الرقم

    رقم تعريف العنصر المطلوب تعديله.

  • updateProperties

    كائن

    السمات المطلوب تعديلها. تقبل القيم نفسها التي تقبلها الدالة contextMenus.create.

    • تم التحديد

      قيمة منطقية اختيارية

    • السياقات

      [ContextType, ...ContextType[]] اختياري

    • documentUrlPatterns

      string[] اختيارية

    • مفعّلة

      قيمة منطقية اختيارية

    • parentId

      string | الرقم اختياري

      معرّف السلعة المطلوب جعلها رئيسية لها ملاحظة: لا يمكنك ضبط عنصر ليصبح عنصرًا فرعيًا تابعًا له.

    • targetUrlPatterns

      string[] اختيارية

    • title

      سلسلة اختيارية

    • كتابة

      ItemType اختياري

    • مرئي

      قيمة منطقية اختيارية

      الإصدار 62 من Chrome أو الإصدارات الأحدث

      ما إذا كان العنصر مرئيًا في القائمة

    • onclick

      null اختياري

      تبدو دالة onclick كما يلي: 

      (info: OnClickData, tab: Tab) => {...}

      • معلومات

        OnClickData

        الإصدار 44 من Chrome أو الإصدارات الأحدث
      • الإصدار 44 من Chrome أو الإصدارات الأحدث

        تفاصيل علامة التبويب التي حدثت فيها النقرة. هذه المعلمة غير متوفرة لتطبيقات النظام الأساسي.

  • رد الاتصال

    الدالة اختيارية

    تظهر المَعلمة callback على النحو التالي: 

    () => void

المرتجعات

  • وعود <باطلة>

    الإصدار 123 من Chrome أو الإصدارات الأحدث

    تتوفّر الوعود في الإصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير معاودة الاتصال. التوافق مع الأنظمة القديمة. لا يمكنك استخدام كلتيهما في نفس استدعاء الدالة. تشير رسالة الأشكال البيانية يتم حل الوعد بنفس النوع الذي يتم إرساله إلى معاودة الاتصال.

فعاليات

onClicked

chrome.contextMenus.onClicked.addListener(
  callback: function,
)

يتم إطلاقه عند النقر على عنصر في قائمة السياقات.

المعلمات

  • رد الاتصال

    دالة

    تظهر المَعلمة callback على النحو التالي: 

    (info: OnClickData, tab?: tabs.Tab) => void