الوصف
يمكنك استخدام واجهة برمجة التطبيقات chrome.contextMenus
API لإضافة عناصر إلى قائمة سياقات 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 على تصغيرها تلقائيًا في قائمة رئيسية واحدة.
أمثلة
لتجربة واجهة برمجة التطبيقات هذه، يُرجى تثبيت مثال واجهة برمجة التطبيقات contextLists API من مستودع chrome-extension-patterns.
الأنواع
ContextType
السياقات المختلفة التي يمكن أن تظهر فيها القائمة. إنّ تحديد "الكل" يكافئ مجموعة جميع السياقات الأخرى باستثناء "مشغّل التطبيقات". لا يتوافق سياق "مشغّل التطبيقات" إلا مع التطبيقات ويتم استخدامه لإضافة عناصر القائمة إلى قائمة السياق التي تظهر عند النقر على رمز التطبيق في مشغّل التطبيقات أو شريط المهام أو لوحة الإرساء أو ما إلى ذلك. وقد تفرض الأنظمة الأساسية المختلفة قيودًا على العناصر المتاحة فعليًا في قائمة سياق مشغّل التطبيقات.
التعداد
"audio"
"browser_action"
"page_action"
"action"
CreateProperties
خصائص عنصر قائمة السياق الجديد.
أماكن إقامة
-
تم وضع علامة في المربّع
منطقية اختيارية
الحالة الأولية لمربّع اختيار أو زر اختيار:
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" واختيار المستخدم كلمة "cool"، يكون عنصر قائمة السياق المحدد هو "ترجمة كلمة "رائع" إلى اللغة اللاتينية". -
كتابة
ItemType اختيارية
نوع صنف في القائمة وتكون الإعدادات التلقائية
normal
. -
مرئي
منطقية اختيارية
ما إذا كان العنصر مرئيًا في القائمة.
-
onclick
باطل اختياري
دالة يتم استدعاءها مرة أخرى عند النقر فوق عنصر القائمة. لا تتوفّر هذه الميزة داخل مشغّل الخدمات، بل عليك بدلاً من ذلك تسجيل أداة تلقّ�� إشعارات في
contextMenus.onClicked
.تبدو الدالة
onclick
على النحو التالي:(info: OnClickData, tab: Tab) => {...}
-
معلومات
معلومات عن السلعة التي تم النقر عليها والسياق الذي حدثت فيه النقرة
-
تفاصيل علامة التبويب التي حدثت فيها النقرة. هذه المَعلمة غير متوفّرة لتطبيقات النظام الأساسي.
-
ItemType
نوع صنف في القائمة
التعداد
OnClickData
المعلومات التي يتم إرسالها عند النقر على عنصر في قائمة السياق.
أماكن إقامة
-
تم وضع علامة في المربّع
منطقية اختيارية
علامة تشير إلى حالة مربّع اختيار أو عنصر اختيار بعد النقر عليه.
-
قابلة للتعديل
boolean
علامة تشير إلى ما إذا كان العنصر قابلاً للتعديل (إدخال النص أو منطقة النص وغير ذلك).
-
frameId
الرقم اختياري
Chrome 51 والإصدارات الأحدثرقم تعريف الإطار للعنصر الذي تم النقر فيه على قائمة السياق، إذا كانت ضمن إطار.
-
frameUrl
سلسلة اختيارية
عنوان URL لإطار العنصر حيث تم النقر على قائمة السياق، إذا كانت في إطار.
-
linkUrl
سلسلة اختيارية
إذا كان العنصر رابطًا، فإن عنوان URL الذي يشير إليه.
-
mediaType
سلسلة اختيارية
إما "صورة" أو "فيديو" أو "صوت" إذا تم تفعيل قائمة السياق على أحد هذه الأنواع من العناصر.
-
سلسلة | رقم
رقم تعريف صنف في القائمة الذي تم النقر عليه
-
pageUrl
سلسلة اختيارية
عنوان URL للصفحة التي تم النقر فيها على عنصر في القائمة لا يتم ضبط هذه السمة في حال حدوث النقر في سياق لا تتوفّر فيه صفحة حالية، مثل قائمة سياقات مشغّل التطبيقات.
-
parentMenuItemId
سلسلة | رقم اختياري
رقم التعريف الرئيسي، في حال توفّره، للعنصر الذي تم النقر عليه
-
selectionText
سلسلة اختيارية
تمثّل هذه السمة النص لاختيار السياق، إن وجد.
-
srcUrl
سلسلة اختيارية
سيتم عرضه للعناصر التي ل��ا عنو��ن URL 'src'.
-
wasChecked
منطقية اختيارية
علامة تشير إلى حالة مربّع اختيار أو عنصر اختيار قبل النقر عليه.
أماكن إقامة
ACTION_MENU_TOP_LEVEL_LIMIT
الحدّ الأقصى لعدد عناصر الإضافة ذات المستوى الأعلى التي يمكن إضافتها إلى قائمة سياق إجراء الإضافة. وسيتم تجاهل أي عناصر تتجاوز هذا الحدّ.
القيمة
6
الطُرق
create()
chrome.contextMenus.create(
createProperties: CreateProperties,
callback?: function,
)
ينشئ عنصرًا جديدًا في قائمة السياق. في حال حدوث خطأ أثناء الإنشاء، قد لا يتم رصده إلى أن يتم تنشيط معاودة الاتصال بشأن الإنشاء، وستكون التفاصيل في runtime.lastError
.
المَعلمات
-
createProperties
-
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
callback
على النحو التالي:() => void
المرتجعات
-
العدد | سلسلة
رقم تعريف العنصر الذي تم إنشاؤه حديثًا.
remove()
chrome.contextMenus.remove(
menuItemId: string | number,
callback?: function,
)
لإزالة عنصر في قائمة السياقات.
المَعلمات
-
سلسلة | رقم
رقم تعريف عنصر قائمة السياق المطلوب إزالته.
-
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
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 اختيارية
-
مرئي
منطقية اختيارية
الإصدار 62 من Chrome والإصدارات الأحدثما إذا كان العنصر مرئيًا في القائمة.
-
onclick
باطل اختياري
تبدو الدالة
onclick
على النحو التالي:(info: OnClickData, tab: Tab) => {...}
-
معلوماتChrome 44 والإصدارات الأحدث
-
Chrome 44 والإصدارات الأحدث
تفاصيل علامة التبويب التي حدثت فيها النقرة. هذه المَعلمة غير متوفّرة لتطبيقات النظام الأساسي.
-
-
-
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
callback
على النحو التالي:() => void
المرتجعات
-
Promise<void>
Chrome 123 والإصدارات الأحدثتتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.
فعاليات
onClicked
chrome.contextMenus.onClicked.addListener(
callback: function,
)
يتم تنشيطها عند النقر على عنصر في قائمة السياق.
المَعلمات
-
معاودة الاتصال
الوظيفة
تبدو معلَمة
callback
على النحو التالي:(info: OnClickData, tab?: tabs.Tab) => void
-
معلومات
-
tabs.Tab اختيارية
-