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"
  },
  ...
}

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

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

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

أمثلة

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

الأنواع

ContextType

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

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

Enum

"all"

"page"

"frame"

"selection"

"link"

"editable"

"image"

"video"

"audio"

"launcher"

"browser_action"

"page_action"

"action"

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 والإصدارات الأحدث

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

Enum

"normal"

"checkbox"

"radio"

"separator"

OnClickData

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

الخصائص

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

    boolean اختياري

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

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

    قيمة منطقية

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

  • frameId

    number اختياري

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

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

  • 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

المرتجعات

  • number | string

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

remove()

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

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

المعلمات

  • menuItemId

    سلسلة | رقم

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

المرتجعات

  • Promise<void>

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

removeAll()

chrome.contextMenus.removeAll(): Promise<void>

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

المرتجعات

  • Promise<void>

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

update()

chrome.contextMenus.update(
  id: string | number,
  updateProperties: object,
): 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 والإصدارات الأحدث

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

المرتجعات

  • Promise<void>

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

الفعاليات

onClicked

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

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

المعلمات

  • callback

    دالة

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

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