chrome.contextMenus

refresh date: 2026-09-25 robots: noindex

الوصف

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

الأذونات

contextMenus

الاستخدام

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

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

البيان

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

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

أمثلة

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

الأنواع

ContextType

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

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

Enum

"all"

"page"

"frame"

"selection"

"link"

"editable"

"image"

"video"

"audio"

"launcher"

"action"
ينطبق على قائمة السياق الخاصة بإجراء الإضافة (رمز شريط الأدوات).

"tab"
تنطبق على قائمة السياق الخاصة بعلامة تبويب في شريط علامات التبويب.

CreateProperties

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

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

الخصائص

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

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

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

  • contexts

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

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

  • documentUrlPatterns

    string[] اختياري

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

  • مفعّلة

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

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

  • id

    string اختياري

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

  • parentId

    string | number اختيارية

    رقم تعريف عنصر قائمة رئيسي، ما يجعل العنصر فرعيًا لعنصر تمت إضافته سابقًا.

  • targetUrlPatterns

    string[] اختياري

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

  • title

    string اختياري

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

  • النوع

    ItemType اختياري

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

  • مرئي

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

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

  • onclick

    void اختياري

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

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

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

    • معلومات

      OnClickData

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

    • تفاصيل علامة التبويب التي تم النقر عليها لا تتوفّر هذه المَعلمة لتطبيقات المنصّة.

ItemType

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

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

Enum

"normal"

"checkbox"

"radio"

"separator"

OnClickData

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

الخصائص

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

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

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

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

    قيمة منطقية

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

  • frameId

    number اختيارية

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

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

  • frameUrl

    string اختياري

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

  • linkUrl

    string اختياري

    إذا كان العنصر رابطًا، يشير هذا الحقل إلى عنوان URL الذي يؤدي إليه.

  • mediaType

    string اختياري

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

  • menuItemId

    string | number

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

  • pageUrl

    string اختياري

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

  • parentMenuItemId

    string | number اختيارية

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

  • selectionText

    string اختياري

    النص الخاص باختيار السياق، إن توفّر.

  • srcUrl

    string اختياري

    ستظهر للعناصر التي تحتوي على عنوان URL من النوع "src".

  • wasChecked

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

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

الخصائص

ACTION_MENU_TOP_LEVEL_LIMIT

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

القيمة

6

الطُرق

create()

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

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

المعلمات

  • createProperties

    CreateProperties

  • callback

    function اختياري

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

    () => void

المرتجعات

  • number | string

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

remove()

Promise 
chrome.contextMenus.remove(
  menuItemId: string | number,
  callback?: function,
): Promise<void>

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

المعلمات

  • menuItemId

    string | number

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

  • callback

    function اختياري

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

    () => void

المرتجعات

  • وعد<فراغ>

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

    يتم حلّ المشكلة عند إزالة قائمة السياق.

    لا تتوفّر الوعود إلا في الإصدار Manifest V3 والإصدارات الأحدث، وتحتاج المنصات الأخرى إلى استخدام عمليات الاستدعاء.

removeAll()

Promise 
chrome.contextMenus.removeAll(
  callback?: function,
): Promise<void>

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

المعلمات

  • callback

    function اختياري

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

    () => void

المرتجعات

  • وعد<فراغ>

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

    يتم حلّ المشكلة عند اكتمال عملية الإزالة.

    لا تتوفّر الوعود إلا في الإصدار Manifest V3 والإصدارات الأحدث، وتحتاج المنصات الأخرى إلى استخدام عمليات الاستدعاء.

update()

Promise 
chrome.contextMenus.update(
  id: string | number,
  updateProperties: object,
  callback?: function,
): Promise<void>

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

المعلمات

  • id

    string | number

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

  • updateProperties

    عنصر

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

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

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

    • contexts

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

    • documentUrlPatterns

      string[] اختياري

    • مفعّلة

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

    • parentId

      string | number اختيارية

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

    • targetUrlPatterns

      string[] اختياري

    • title

      string اختياري

    • النوع

      ItemType اختياري

    • مرئي

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

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

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

    • onclick

      void اختياري

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

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

      • معلومات

        OnClickData

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

        تفاصيل علامة التبويب التي تم النقر عليها لا تتوفّر هذه المَعلمة لتطبيقات المنصّة.

  • callback

    function اختياري

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

    () => void

المرتجعات

  • وعد<فراغ>

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

    يتم حلّ المشكلة عند تعديل قائمة السياق.

    لا تتوفّر الوعود إلا في الإصدار Manifest V3 والإصدارات الأحدث، وتحتاج المنصات الأخرى إلى استخدام عمليات الاستدعاء.

الفعاليات

onClicked

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

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

المعلمات

  • callback

    دالة

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

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