تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

chrome.contextMenus

الوصف

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

الأذونات

contextMenus

يجب الإفصاح عن الإذن "contextMenus" في ملف بيان الإضافة لاستخدام واجهة برمجة التطبيقات. بالإضافة إلى ذلك، يجب تحديد رمز أبعاده 16 x ‏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 والإصدارات الأحدث

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

Enum

"all"

"page"

"frame"

"selection"

"link"

"editable"

"image"

"video"

"audio"

"launcher"

"browser_action"

"page_action"

"action"

CreateProperties

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

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

أماكن إقامة

تم التحديد

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

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

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

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

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

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

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

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

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

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

سلسلة | رقم اختياري

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

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

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

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

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

‫ItemType اختيارية

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

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

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

void اختياري

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

تبدو الدالة onclick على النحو التالي:
```
(info: OnClickData, tab: Tab) => {...}
```
- معلومات
  
  OnClickData
  
  معلومات عن العنصر الذي تم النقر عليه والسياق الذي حدثت فيه النقرة
- tab
  
  علامة التبويب
  
  تفاصيل علامة التبويب التي حدثت فيها النقرة لا تتوفّر هذه المَعلمة لتطبيقات النظام الأساسي.

ItemType

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

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

Enum

"normal"

"checkbox"

"radio"

"separator"

OnClickData

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

أماكن إقامة

تم التحديد

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

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

قيمة منطقية

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

رقم اختياري

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

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

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

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

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

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

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

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

سلسلة | رقم

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

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

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

سلسلة | رقم اختياري

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

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

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

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

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

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

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

أماكن إقامة

ACTION_MENU_TOP_LEVEL_LIMIT

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

القيمة

الطُرق

create()

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

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

المعلمات

createProperties

CreateProperties
ردّ الاتصال

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

تظهر المَعلمة callback على النحو التالي:
```
() => void
```

المرتجعات

عدد | سلسلة

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

remove()

الوعد

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

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

المعلمات

menuItemId

سلسلة | رقم

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

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

تظهر المَعلمة 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

سلسلة | رقم

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

عنصر

السمات المطلوب تعديلها تقبل الدالة القيم نفسها التي تقبلها الدالة contextMenus.create.
- تم التحديد
  
  منطقي اختياري
- السياقات
  
  [ContextType, ...ContextType[]] اختياري
- documentUrlPatterns
  
  سلسلة اختيارية
- مفعّلة
  
  منطقي اختياري
- parentId
  
  سلسلة | رقم اختياري
  
  معرّف العنصر الذي سيتمّ جعله العنصر الرئيسي لهذا العنصر. ملاحظة: لا يمكنك ضبط عنصر ليصبح عنصرًا فرعيًا لعنصر فرعي له.
- targetUrlPatterns
  
  سلسلة اختيارية
- title
  
  سلسلة اختيارية
- كتابة
  
  ‫ItemType اختيارية
- مرئي
  
  منطقي اختياري
  
  Chrome 62 والإصدارات الأحدث
  
  ما إذا كان العنصر مرئيًا في القائمة
- onclick
  
  void اختياري
  
  تبدو الدالة onclick على النحو التالي:
```
(info: OnClickData, tab: Tab) => {...}
```
  - معلومات
    
    OnClickData
    
    Chrome 44 والإصدارات الأحدث
  - tab
    
    علامة التبويب
    
    Chrome 44 والإصدارات الأحدث
    
    تفاصيل علامة التبويب التي حدثت فيها النقرة لا تتوفّر هذه المَعلمة لتطبيقات النظام الأساسي.
ردّ الاتصال

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

تظهر المَعلمة callback على النحو التالي:
```
() => void
```

المرتجعات

Promise<void>

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

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

الفعاليات

onClicked

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

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

المعلمات

ردّ الاتصال

دالة

تظهر المَعلمة callback على النحو التالي:
```
(info: OnClickData, tab?: tabs.Tab) => void
```
- معلومات
  
  OnClickData
- tab
  
  tabs.Tab اختياري