chrome.contextMenus

الوصف

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

الأذونات

contextMenus

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

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

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

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

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

أمثلة

لتجربة واجهة برمجة التطبيقات هذه، يُرجى تثبيت مثال واجهة برمجة التطبيقات contextLists API من مستودع chrome-extension-patterns.

الأنواع

ContextType

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

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

التعداد

"audio"

"browser_action"

"page_action"

"action"

CreateProperties

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

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

أماكن إقامة

  • تم وضع علامة في المربّع

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

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

  • السياقات

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

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

  • documentUrlPatterns

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

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

  • مفعّلة

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

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

  • id

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

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

  • parentId

    string|number اختياري

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

  • targetUrlPatterns

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

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

  • title

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

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

  • كتابة

    ItemType اختيارية

    نوع صنف في القائمة وتكون الإعدادات التلقائية normal.

  • مرئي

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

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

  • onclick

    باطل اختياري

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

    تبدو الدالة onclick على النحو التالي: 

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

    • معلومات

      OnClickData

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

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

ItemType

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

نوع صنف في القائمة

التعداد

OnClickData

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

أماكن إقامة

  • تم وضع علامة في المربّع

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

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

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

    boolean

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

  • frameId

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

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

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

  • frameUrl

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

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

  • linkUrl

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

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

  • mediaType

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

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

  • menuItemId

    string|number

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

  • pageUrl

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

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

  • parentMenuItemId

    string|number اختياري

    رقم التعريف الرئيسي، في حال توفّره، للعنصر الذي تم النقر عليه

  • selectionText

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

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

  • srcUrl

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

    سيتم عرضه للعناصر التي لها عنوان URL 'src'.

  • wasChecked

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

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

أماكن إقامة

ACTION_MENU_TOP_LEVEL_LIMIT

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

القيمة

6

الطُرق

create()

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

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

المَعلمات

  • createProperties

    CreateProperties

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

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

    تبدو معلَمة callback على النحو التالي: 

    ()=>void

المرتجعات

  • number|string

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

remove()

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

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

المَعلمات

  • menuItemId

    string|number

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

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

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

    تبدو معلَمة callback على النحو التالي: 

    ()=>void

المرتجعات

  • Promise<void>

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

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

removeAll()

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

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

المَعلمات

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

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

    تبدو معلَمة callback على النحو التالي: 

    ()=>void

المرتجعات

  • Promise<void>

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

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

update()

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

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

المَعلمات

  • id

    string|number

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

  • updateProperties

    كائن

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

    • تم وضع علامة في المربّع

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

    • السياقات

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

    • documentUrlPatterns

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

    • مفعّلة

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

    • parentId

      string|number اختياري

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

    • targetUrlPatterns

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

    • title

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

    • كتابة

      ItemType اختيارية

    • مرئي

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

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

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

    • onclick

      باطل اختياري

      تبدو الدالة onclick على النحو التالي: 

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

      • معلومات

        OnClickData

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

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

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

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

    تبدو معلَمة callback على النحو التالي: 

    ()=>void

المرتجعات

  • Promise<void>

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

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

فعاليات

onClicked

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

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

المَعلمات

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

    الوظيفة

    تبدو معلَمة callback على النحو التالي: 

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