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

chrome.contextMenus

الوصف

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

الأذونات

contextMenus

الاستخدام

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

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

البيان

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

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

أمثلة

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

الأنواع

ContextType

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

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

Enum

"الكل"

"الصفحة"

"الإطار"

"الاختيار"

"الرابط"

"تعديل"

"صورة"

"الفيديو"

"audio"

"مشغّل التطبيقات"

"browser_action"

"page_action"

الإجراء

CreateProperties

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

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

أماكن إقامة

تم التحديد

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

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

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

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

string[] اختيارية

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

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

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

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

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

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

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

string[] اختيارية

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

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

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

ItemType اختياري

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

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

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

null اختياري

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

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

ItemType

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

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

Enum

"عادي"

"مربّع الاختيار"

"راديو"

"الفاصل"

OnClickData

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

أماكن إقامة

تم التحديد

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

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

منطقي

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

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

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

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

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

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

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

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

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

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

string | الرقم

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

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

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

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

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

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

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

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

ستكون متوفّرة للعناصر التي تحتوي على "src" عنوان URL.
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

string | الرقم

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

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

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

المرتجعات

وعود <باطلة>

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

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

removeAll()

وعود

chrome.contextMenus.removeAll(
  callback?: function,
)

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

المعلمات

رد الاتصال

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

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

المرتجعات

وعود <باطلة>

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

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

update()

وعود

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

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

المعلمات

id

string | الرقم

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

كائن

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

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

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

المرتجعات

وعود <باطلة>

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

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

فعاليات

onClicked

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

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

المعلمات

رد الاتصال

دالة

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