chrome.contextMenus

refresh date: 2026-09-25 robots: noindex

الوصف

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

الأذونات

contextMenus

الاستخدام

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

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

البيان

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

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

أمثلة

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

الأنواع

ContextType

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

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

تعداد

"all"

"page"

"frame"

"selection"

"link"

"editable"

"image"

"video"

"audio"

"launcher"

"browser_action"

"page_action"

"action"

"tab"

CreateProperties

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

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

الخصائص

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

    boolean اختياري

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

  • السياقات

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

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

  • documentUrlPatterns

    string[] اختياري

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

  • مفعّلة

    boolean اختياري

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

  • id

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

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

  • parentId

    string | number اختياري

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

  • targetUrlPatterns

    string[] اختياري

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

  • title

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

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

  • النوع

    ‫ItemType اختيارية

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

  • مرئي

    boolean اختياري

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

  • onclick

    void اختياري

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

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

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

    • معلومات

      OnClickData

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

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

ItemType

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

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

تعداد

"normal"

"checkbox"

"radio"

"separator"

OnClickData

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

الخصائص

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

    boolean اختياري

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

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

    قيمة منطقية

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

  • frameId

    number اختياري

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

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

  • frameUrl

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

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

  • linkUrl

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

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

  • mediaType

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

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

  • menuItemId

    سلسلة | رقم

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

  • pageUrl

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

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

  • parentMenuItemId

    string | number اختياري

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

  • selectionText

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

    تمثّل هذه السمة النص الخاص بالجزء المحدّد من السياق، إذا كان ذلك منطبقًا.

  • srcUrl

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

    سيكون هذا السمة متوفّرًا للعناصر التي تتضمّن عنوان URL "src".

  • wasChecked

    boolean اختياري

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

الخصائص

ACTION_MENU_TOP_LEVEL_LIMIT

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

القيمة

6

الطُرق

create()

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

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

المعلمات

  • createProperties

    CreateProperties

  • callback

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

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

    () => void

المرتجعات

  • رقم | سلسلة

    معرّف السلعة التي تم إنشاؤها حديثًا.

remove()

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

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

المعلمات

  • menuItemId

    سلسلة | رقم

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

  • callback

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

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

    () => void

المرتجعات

  • Promise<void>

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

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

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

removeAll()

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

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

المعلمات

  • callback

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

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

    () => void

المرتجعات

  • Promise<void>

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

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

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

update()

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

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

المعلمات

  • id

    سلسلة | رقم

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

  • updateProperties

    عنصر

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

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

      boolean اختياري

    • السياقات

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

    • documentUrlPatterns

      string[] اختياري

    • مفعّلة

      boolean اختياري

    • parentId

      string | number اختياري

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

    • targetUrlPatterns

      string[] اختياري

    • title

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

    • النوع

      ‫ItemType اختيارية

    • مرئي

      boolean اختياري

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

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

    • onclick

      void اختياري

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

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

      • معلومات

        OnClickData

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

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

  • callback

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

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

    () => void

المرتجعات

  • Promise<void>

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

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

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

الفعاليات

onClicked

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

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

المعلمات

  • callback

    دالة

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

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