الوصف
استخدم إجراءات المتصفح لوضع الرموز في شريط أدوات Google Chrome الرئيسي، على يسار شريط العناوين. بالإضافة إلى رمزه، قد يتضمن إجراء المتصفح تلميح وشارة ونافذة منبثقة.
مدى التوفّر
في الشكل التالي، يمثّل المربّع متعدد الألوان على يمين شريط العناوين رمز أحد إجراءات المتصفّح. ستظهر نافذة منبثقة أسفل الرمز.
إذا كنت تريد إنشاء رمز غير نشط دائمًا، استخدِم إجراء صفحة بدلاً من أحد إجراءات المتصفّح.
البيان
سجِّل إجراء المتصفّح في بيان الإضافة على النحو التالي:
{
"name": "My extension",
...
"browser_action": {
"default_icon": { // optional
"16": "images/icon16.png", // optional
"24": "images/icon24.png", // optional
"32": "images/icon32.png" // optional
},
"default_title": "Google Mail", // optional, shown in tooltip
"default_popup": "popup.html" // optional
},
...
}
يمكنك توفير أي رمز حجم لاستخدامه في Chrome، وسيختار Chrome أقرب رمز ويضبطه بالحجم المناسب لملء المساحة المكوّنة من 16 قطعة. ومع ذلك، إذا لم يتم توفير الحجم الدقيق، فقد يؤدي هذا التحجيم إلى فقدان الأيقونة للتفاصيل أو الظهور بشكل ضبابي.
نظرًا لأن الأجهزة ذات عوامل المقياس الأقل شيوعًا مثل 1.5x أو 1.2x أصبحت أكثر شيوعًا، فننصحك بتوفير أحجام متعددة لرموزك. يضمن هذا أيضًا أنه إذا تم تغيير حجم عرض الأيقونة، فلن تحتاج إلى القيام بأي مزيد من العمل لتوفير أيقونات مختلفة!
لا تزال البنية القديمة لتسجيل الرمز الافتراضي متوفرة:
{
"name": "My extension",
...
"browser_action": {
...
"default_icon": "images/icon32.png" // optional
// equivalent to "default_icon": { "32": "images/icon32.png" }
},
...
}
أجزاء واجهة المستخدم
قد يحتوي إجراء المتصفح على رمز وتلميح وشارة ونافذة منبثقة.
الرمز
يبلغ عرض رموز الإجراءات في Chrome وارتفاعها 16 نقطة (بكسل مستقل عن الجهاز). يتم تغيير حجم الأيقونات الأكبر حجمًا لتلائم الحجم، ولكن للحصول على أفضل النتائج، استخدِم أيقونة مربّعة الشكل من 16 تراجعًا.
يمكنك ضبط الرمز بطريقتَين: باستخدام صورة ثابتة أو باستخدام عنصر لوحة الرسم HTML5. يسهل استخدام الصور الثابتة في التطبيقات البسيطة، ولكن يمكنك إنشاء المزيد من واجهات المستخدم الديناميكية - مثل الرسوم المتحركة السلسة - باستخدام عنصر لوحة الرسم.
يمكن أن تكون الصور الثابتة بأي تنسيق يمكن أن تعرضه WebKit، بما في ذلك BMP أو GIF أو ICO أو JPEG أو PNG. بالنسبة إلى الإضافات غير المضغوطة، يجب أن تكون الصور بتنسيق PNG.
لضبط الرمز، استخدِم الحقل default_icon من default_icon في البيان، أو استدعِ الطريقة browserAction.setIcon
.
لعرض الرمز بشكل صحيح عندما تكون كثافة وحدات البكسل في الشاشة (النسبة المئوية size_in_pixel / size_in_dip
) مختلفة عن
1، يمكن تعريف الرمز كمجموعة صور بأحجام مختلفة. وسيتم اختيار الصورة التي سيتم عرضها من المجموعة لتلائم حجم البكسل 16 انخفاضًا على أفضل وجه. يمكن أن تحتوي مجموعة الأيقونات على أي مواصفات
للرموز، وسيختار Chrome الأكثر ملاءمة.
تلميح
لضبط التلميح، استخدِم الحقل default_title في default_title في البيان، أو اطلب الإجراء browserAction.setTitle
. ويمكنك تحديد سلاسل خاصة بالمنطقة المحلية للحقل
default_title. ويمكنك الاطّلاع على القسم الانتشار على نطاق عالمي للحصول على التفاصيل.
الشارة
يمكن أن تعرض إجراءات المتصفّح شارة بشكل اختياري، وهي عبارة عن جزء من النص يظهر فوق الرمز. وتسهّل الشارات تحديث إجراء المتصفّح لعرض قدر صغير من المعلومات حول حالة الإضافة.
يجب ألا يزيد عدد أحرف الشارة عن 4 أحرف لأنّ مساحة الشارة محدودة.
اضبط نص الشارة ولونها باستخدام browserAction.setBadgeText
وbrowserAction.setBadgeBackgroundColor
على التوالي.
نافذة منبثقة
إذا تضمّنت إجراءات المتصفّح نافذة منبثقة، ستظهر النافذة المنبثقة عندما ينقر المستخدم على رمز الإضافة. يمكن أن تحتوي النافذة المنبثقة على أي محتوى HTML يعجبك، ويتم تغيير حجمها تلقائيًا لتلائم محتواها. لا يمكن أن تكون النافذة المنبثقة أصغر من 25x25 ولا يمكن أن تكون أكبر من 800x600.
لإضافة نافذة منبثقة إلى إجراء المتصفِّح، أنشِئ ملف HTML يتضمّن محتوى النافذة المنبثقة. حدِّد ملف HTML في الحقل default_popup من default_popup في البيان أو استدعِ الإجراء
browserAction.setPopup
.
نصائح
للحصول على أفضل تأثير مرئي، اتبع الإرشادات التالية:
- استخدِم إجراءات المتصفّح للميزات المناسبة في معظم الصفحات.
- لا تستخدم إجراءات المتصفّح للميزات التي قد تفيد بضع صفحات فقط. استخدِم إجراءات الصفحة بدلاً من ذلك.
- استخدِم رموزًا كبيرة وملوّنة تستفيد إلى أقصى حدّ من المساحة التي تبلغ مساحتها 16x16. يجب أن تبدو أيقونات إجراءات المتصفح أكبر قليلاً وأثقل من أيقونات إجراءات الصفحة.
- لا تحاول تقليد رمز القائمة الأحادية اللون في Google Chrome. هذا لا يعمل بشكل جيد مع النُسُق، وعلى أي حال، يجب أن تبرز الإضافات قليلاً.
- استخدِم الشفافية ألفا لإضافة حواف ناعمة إلى الرمز. نظرًا لأن العديد من الأشخاص يستخدمون سمات، فيجب أن تبدو أيقونةك لطيفة على مجموعة متنوعة من ألوان الخلفية.
- لا تحرّك الرمز باستمرار. هذا فقط مزعج.
أمثلة
يمكنك العثور على أمثلة بسيطة لاستخدام إجراءات المتصفح في الدليل examples/api/browserAction. للحصول على أمثلة أخرى والحصول على مساعدة في عرض رمز المصدر، يُرجى مراجعة عيّنات.
الأنواع
ColorArray
النوع
[رقم، رقم، رقم]
ImageDataType
بيانات البكسل لصورة ما يجب أن يكون كائن ImageData، على سبيل المثال، من عنصر canvas
.
النوع
ImageData
TabDetails
أماكن إقامة
-
tabId
الرقم اختياري
رقم تعريف علامة التبويب المطلوب الاستعلام عنها إذا لم يتم تحديد أي علامة تبويب، يتم عرض الحالة غير الخاصة بعلامة التبويب.
الطُرق
disable()
chrome.browserAction.disable(
tabId?: number,
callback?: function,
)
لإيقاف إجراء المتصفح لعلامة تبويب.
المَعلمات
-
tabId
الرقم اختياري
رقم تعريف علامة التبويب التي تريد تعديل إجراء المتصفّح لها.
-
معاودة الاتصال
الدالة اختيارية
الإصدار 67 من Chrome والإصدارات الأحدثتبدو معلَمة
callback
على النحو التالي:() => void
المرتجعات
-
Promise<void>
Chrome 88 والإصدارات الأحدثلا تتوفّر الوعود إلا في الإصدار 3 من Manifest V3 والإصدارات الأحدث، وتحتاج الأنظمة الأساسية الأخرى إلى استخدام عمليات معاودة الاتصال.
enable()
chrome.browserAction.enable(
tabId?: number,
callback?: function,
)
تمكِّن هذه السياسة إجراء المتصفّح في علامة تبويب. يكون الإعداد التلقائي مفعّلاً.
المَعلمات
-
tabId
الرقم اختياري
رقم تعريف علامة التبويب التي تريد تعديل إجراء المتصفّح لها.
-
معاودة الاتصال
الدالة اختيارية
الإصدار 67 من Chrome والإصدارات الأحدثتبدو معلَمة
callback
على النحو التالي:() => void
المرتجعات
-
Promise<void>
Chrome 88 والإصدارات الأحدثلا تتوفّر الوعود إلا في الإصدار 3 من Manifest V3 والإصدارات الأحدث، وتحتاج الأنظمة الأساسية الأخرى إلى استخدام عمليات معاودة الاتصال.
getBadgeBackgroundColor()
chrome.browserAction.getBadgeBackgroundColor(
details: TabDetails,
callback?: function,
)
الحصول على لون الخلفية لإجراء المتصفّح.
المَعلمات
-
التفاصيل
-
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
callback
على النحو التالي:(result: ColorArray) => void
-
نتيجة
-
المرتجعات
-
Promise<ColorArray>
Chrome 88 والإصدارات الأحدثلا تتوفّر الوعود إلا في الإصدار 3 من Manifest V3 والإصدارات الأحدث، وتحتاج الأنظمة الأساسية الأخرى إلى استخدام عمليات معاودة الاتصال.
getBadgeText()
chrome.browserAction.getBadgeText(
details: TabDetails,
callback?: function,
)
الحصول على نص الشارة لإجراء المتصفّح. إذا لم يتمّ تحديد أي علامة تبويب، يتم عرض نص الشارة غير الخاص بعلامة التبويب.
المَعلمات
-
التفاصيل
-
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
callback
على النحو التالي:(result: string) => void
-
نتيجة
سلسلة
-
المرتجعات
-
وعد<string>
Chrome 88 والإصدارات الأحدثلا تتوفّر الوعود إلا في الإصدار 3 من Manifest V3 والإصدارات الأحدث، وتحتاج الأنظمة الأساسية الأخرى إلى استخدام عمليات معاودة الاتصال.
getPopup()
chrome.browserAction.getPopup(
details: TabDetails,
callback?: function,
)
الحصول على مستند HTML الذي تم ضبطه كنافذة منبثقة لإجراء المتصفّح هذا.
المَعلمات
-
التفاصيل
-
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
callback
على النحو التالي:(result: string) => void
-
نتيجة
سلسلة
-
المرتجعات
-
وعد<string>
Chrome 88 والإصدارات الأحدثلا تتوفّر الوعود إلا في الإصدار 3 من Manifest V3 والإصدارات الأحدث، وتحتاج الأنظمة الأساسية الأخرى إلى استخدام عمليات معاودة الاتصال.
getTitle()
chrome.browserAction.getTitle(
details: TabDetails,
callback?: function,
)
للحصول على عنوان إجراء المتصفّح.
المَعلمات
-
التفاصيل
-
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
callback
على النحو التالي:(result: string) => void
-
نتيجة
سلسلة
-
المرتجعات
-
وعد<string>
Chrome 88 والإصدارات الأحدثلا تتوفّر الوعود إلا في الإصدار 3 من Manifest V3 والإصدارات الأحدث، وتحتاج الأنظمة الأساسية الأخرى إلى استخدام عمليات معاودة الاتصال.
setBadgeBackgroundColor()
chrome.browserAction.setBadgeBackgroundColor(
details: object,
callback?: function,
)
لضبط لون الخلفية للشارة.
المَعلمات
-
التفاصيل
عنصر
-
اللون
سلسلة | ColorArray
مصفوفة من أربعة أعداد صحيحة في النطاق من 0 إلى 255 تشكل لون RGBA للشارة. يمكن أيضًا أن يكون سلسلة ذات قيمة لون سداسية عشرية في CSS، على سبيل المثال،
#FF0000
أو#F00
(أحمر). يتم عرض الألوان بدرجة تعتيم كاملة. -
tabId
الرقم اختياري
لتحديد هذا الخيار فقط، عندما يتم اختيار علامة تبويب معيَّنة. تتم إعادة ضبط علامة التبويب تلقائيًا عند إغلاقها.
-
-
معاودة الاتصال
الدالة اختيارية
الإصدار 67 من Chrome والإصدارات الأحدثتبدو معلَمة
callback
على النحو التالي:() => void
المرتجعات
-
Promise<void>
Chrome 88 والإصدارات الأحدثلا تتوفّر الوعود إلا في الإصدار 3 من Manifest V3 والإصدارات الأحدث، وتحتاج الأنظمة الأساسية الأخرى إلى استخدام عمليات معاودة الاتصال.
setBadgeText()
chrome.browserAction.setBadgeText(
details: object,
callback?: function,
)
تحدِّد هذه السياسة نص الشارة لإجراء المتصفّح. يتم عرض الشارة أعلى الرمز.
المَعلمات
-
التفاصيل
عنصر
-
tabId
الرقم اختياري
لتحديد هذا الخيار فقط، عندما يتم اختيار علامة تبويب معيَّنة. تتم إعادة ضبط علامة التبويب تلقائيًا عند إغلاقها.
-
text
سلسلة اختيارية
يمكن تمرير أي عدد من الأحرف، ولكن لا يمكن أن تناسب المساحة سوى حوالي أربعة أحرف. في حال تمرير سلسلة فارغة (
''
)، سيتم محو نص الشارة. إذا تم تحديدtabId
وكانtext
فارغًا، سيتم محو نص علامة التبويب المحدّدة وسيتم ضبطه تلقائيًا على نص الشارة العامة.
-
-
معاودة الاتصال
الدالة اختيارية
الإصدار 67 من Chrome والإصدارات الأحدثتبدو معلَمة
callback
على النحو التالي:() => void
المرتجعات
-
Promise<void>
Chrome 88 والإصدارات الأحدثلا تتوفّر الوعود إلا في الإصدار 3 من Manifest V3 والإصدارات الأحدث، وتحتاج الأنظمة الأساسية الأخرى إلى استخدام عمليات معاودة الاتصال.
setIcon()
chrome.browserAction.setIcon(
details: object,
callback?: function,
)
تحدِّد هذه السياسة رمز إجراء المتصفّح. يمكن تحديد الرمز كمسار إلى ملف صورة، أو بيانات البكسل من عنصر لوحة رسم، أو كقاموس لأحد هذه العناصر. يجب تحديد السمة path
أو imageData
.
المَعلمات
-
التفاصيل
عنصر
-
imageData
ImageData | كائن اختياري
إما كائن ImageData أو القاموس {size -> ImageData} الذي يمثل الأيقونة المراد ضبطها. إذا تم تحديد الرمز كقاموس، فسيتم اختيار الصورة المستخدمة بناءً على كثافة وحدات البكسل في الشاشة. إذا كان عدد وحدات بكسل الصور التي تلائم وحدة مساحة الشاشة الواحدة يساوي
scale
، سيتم اختيار صورة بحجمscale
* n، حيث تمثل n حجم الرمز في واجهة المستخدم. يجب تحديد صورة واحدة على الأقل. يُرجى العِلم أنّ 'details.imageData = foo' تساوي 'details.imageData = {'16': foo}' -
المسار
سلسلة | كائن اختياري
إما مسار صورة نسبي أو قاموس {size -> سريع صورة نسبية} يشير إلى رمز مطلوب تعيينه. إذا تم تحديد الرمز كقاموس، فسيتم اختيار الصورة المستخدمة بناءً على كثافة وحدات البكسل في الشاشة. إذا كان عدد وحدات بكسل الصور التي تلائم وحدة مساحة الشاشة الواحدة يساوي
scale
، سيتم اختيار صورة بحجمscale
* n، حيث تمثل n حجم الرمز في واجهة المستخدم. يجب تحديد صورة واحدة على الأقل. تجدر الإشارة إلى أن 'details.path = foo' تساوي 'details.path = {'16': foo}' -
tabId
الرقم اختياري
لتحديد هذا الخيار فقط، عندما يتم اختيار علامة تبويب معيَّنة. تتم إعادة ضبط علامة التبويب تلقائيًا عند إغلاقها.
-
-
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
callback
على النحو التالي:() => void
المرتجعات
-
Promise<void>
Chrome 116 والإصدارات الأحدثلا تتوفّر الوعود إلا في الإصدار 3 من Manifest V3 والإصدارات الأحدث، وتحتاج الأنظمة الأساسية الأخرى إلى استخدام عمليات معاودة الاتصال.
setPopup()
chrome.browserAction.setPopup(
details: object,
callback?: function,
)
لضبط مستند HTML ليتم فتحه كنافذة منبثقة عندما ينقر المستخدم على رمز إجراء المتصفح.
المَعلمات
-
التفاصيل
عنصر
-
نافذة منبثقة
سلسلة
المسار النسبي لملف HTML المطلوب عرضه في نافذة منبثقة. في حال ضبطها على السلسلة الفارغة (
''
)، لن تظهر أي نافذة منبثقة. -
tabId
الرقم اختياري
لتحديد هذا الخيار فقط، عندما يتم اختيار علامة تبويب معيَّنة. تتم إعادة ضبط علامة التبويب تلقائيًا عند إغلاقها.
-
-
معاودة الاتصال
الدالة اختيارية
الإصدار 67 من Chrome والإصدارات الأحدثتبدو معلَمة
callback
على النحو التالي:() => void
المرتجعات
-
Promise<void>
Chrome 88 والإصدارات الأحدثلا تتوفّر الوعود إلا في الإصدار 3 من Manifest V3 والإصدارات الأحدث، وتحتاج الأنظمة الأساسية الأخرى إلى استخدام عمليات معاودة الاتصال.
setTitle()
chrome.browserAction.setTitle(
details: object,
callback?: function,
)
تحدّد عنوان إجراء المتصفّح. يظهر هذا العنوان في التلميح.
المَعلمات
-
التفاصيل
عنصر
-
tabId
الرقم اختياري
لتحديد هذا الخيار فقط، عندما يتم اختيار علامة تبويب معيَّنة. تتم إعادة ضبط علامة التبويب تلقائيًا عند إغلاقها.
-
title
سلسلة
السلسلة التي يجب أن يظهر بها إجراء المتصفِّح عند تمرير الماوس فوقه.
-
-
معاودة الاتصال
الدالة اختيارية
الإصدار 67 من Chrome والإصدارات الأحدثتبدو معلَمة
callback
على النحو التالي:() => void
المرتجعات
-
Promise<void>
Chrome 88 والإصدارات الأحدثلا تتوفّر الوعود إلا في الإصدار 3 من Manifest V3 والإصدارات الأحدث، وتحتاج الأنظمة الأساسية الأخرى إلى استخدام عمليات معاودة الاتصال.