chrome.browserAction

الوصف

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

مدى توفّر الخدمة

≤ MV2

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

إذا أردت إنشاء رمز لا يكون نشطًا دائمًا، استخدِم إجراءً على الصفحة بدلاً من متصفّح. اتخاذ القرار.

البيان

سجِّل إجراء المتصفّح في بيان الإضافة كما يلي:

{
  "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 تريده، ويتم تغيير حجمها تلقائيًا ليلائم محتواها. لا يمكن أن يكون حجم النافذة المنبثقة أصغر من 25×25 ولا يمكن أن يزيد عن 800×600.

ولإضافة نافذة منبثقة إلى إجراء المتصفح، أنشئ ملف HTML يشتمل على محتويات النافذة المنبثقة. تحديد HTML في الحقل default_popup في default_popup في البيان، أو يمكنك طلب browserAction.setPopup.

نصائح

للحصول على أفضل تأثير مرئي، اتبع الإرشادات التالية:

  • استخدِم إجراءات المتصفّح للاستفادة من ميزات مفيدة في معظم الصفحات.
  • لا تستخدم إجراءات المتصفح للميزات التي لا تفيد سوى بضع صفحات. استخدام الصفحة الإجراءات بدلاً من ذلك.
  • استخدِم رموزًا كبيرة وملوّنة للاستفادة إلى أقصى حد من مساحة 16x16 الانخفاض. رموز إجراءات المتصفح يجب أن تبدو أكبر وأثقل قليلاً من أيقونات إجراءات الصفحة.
  • لا تحاول تقليد رمز القائمة الأحادي اللون في Google Chrome. هذا لا يعمل بشكل جيد مع المظاهر، وعلى أي حال، يجب أن تبرز الإضافات قليلاً.
  • استخدِم شفافية ألفا لإضافة حواف ناعمة إلى الرمز. نظرًا لأن العديد من الأشخاص يستخدمون النُسُق، رمز التطبيق يجب أن يبدو جميلاً على مجموعة متنوعة من ألوان الخلفية.
  • لا تحرّك الرمز باستمرار. هذا فقط مزعج.

أمثلة

يمكنك العثور على أمثلة بسيطة لاستخدام إجراءات المتصفّح في examples/api/browserAction الدليل. للحصول على أمثلة أخرى والحصول على مساعدة في عرض رمز المصدر، اطّلِع على عيّنات.

الأنواع

ColorArray

النوع

[رقم، رقم، رقم، رقم]

ImageDataType

بيانات بكسل لإحدى الصور يجب أن تكون كائن ImageData. على سبيل المثال، من عنصر canvas.

النوع

ImageData

TabDetails

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

أماكن إقامة

  • tabId

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

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

الطُرق

disable()

وعود 
chrome.browserAction.disable(
  tabId?: number,
  callback?: function,
)

لإيقاف إجراء المتصفح لإحدى علامات التبويب.

المعلمات

  • tabId

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

    رقم تعريف علامة التبويب المطلوب تعديل إجراء المتصفّح لها.

  • رد الاتصال

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

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

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

    () => void

المرتجعات

  • وعود <باطلة>

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

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

enable()

وعود 
chrome.browserAction.enable(
  tabId?: number,
  callback?: function,
)

تفعيل إجراء المتصفح لعلامة تبويب وتكون الإعدادات التلقائية مفعَّلة.

المعلمات

  • tabId

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

    رقم تعريف علامة التبويب المطلوب تعديل إجراء المتصفّح لها.

  • رد الاتصال

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

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

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

    () => void

المرتجعات

  • وعود <باطلة>

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

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

getBadgeBackgroundColor()

وعود 
chrome.browserAction.getBadgeBackgroundColor(
  details: TabDetails,
  callback?: function,
)

الحصول على لون الخلفية لإجراء المتصفح

المعلمات

  • التفاصيل

    TabDetails

  • رد الاتصال

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

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

    (result: ColorArray) => void

المرتجعات

  • Promise&lt;ColorArray&gt;

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

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

getBadgeText()

وعود 
chrome.browserAction.getBadgeText(
  details: TabDetails,
  callback?: function,
)

يحصل على نص الشارة الخاص بإجراء المتصفح. في حال عدم تحديد علامة تبويب، سيتم عرض نص الشارة الذي لا يرتبط بعلامة تبويب.

المعلمات

  • التفاصيل

    TabDetails

  • رد الاتصال

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

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

    (result: string) => void

    • نتيجة

      سلسلة

المرتجعات

  • وعود<string>

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

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

getPopup()

وعود 
chrome.browserAction.getPopup(
  details: TabDetails,
  callback?: function,
)

يحصل على مستند HTML الذي تم ضبطه كنافذة منبثقة لإجراء المتصفح هذا.

المعلمات

  • التفاصيل

    TabDetails

  • رد الاتصال

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

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

    (result: string) => void

    • نتيجة

      سلسلة

المرتجعات

  • وعود<string>

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

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

getTitle()

وعود 
chrome.browserAction.getTitle(
  details: TabDetails,
  callback?: function,
)

يحصل على عنوان إجراء المتصفّح.

المعلمات

  • التفاصيل

    TabDetails

  • رد الاتصال

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

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

    (result: string) => void

    • نتيجة

      سلسلة

المرتجعات

  • وعود<string>

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

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

setBadgeBackgroundColor()

وعود 
chrome.browserAction.setBadgeBackgroundColor(
  details: object,
  callback?: function,
)

لضبط لون الخلفية للشارة.

المعلمات

  • التفاصيل

    كائن

    • اللون

      string | ColorArray

      مصفوفة من أربعة أعداد صحيحة في النطاق من 0 إلى 255، وتتكون لون الشارة من نموذج RGBA (أحمر أخضر أزرق). يمكن أيضًا أن يكون سلسلة ذات قيمة لون سداسية عشرية لـ CSS؛ على سبيل المثال، #FF0000 أو #F00 (أحمر). يعرض الألوان بدرجة تعتيم كاملة.

    • tabId

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

      يؤدي هذا الخيار إلى تقييد التغيير إلى وقت اختيار علامة تبويب معيَّنة. تتم إعادة الضبط تلقائيًا عند إغلاق علامة التبويب.

  • رد الاتصال

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

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

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

    () => void

المرتجعات

  • وعود <باطلة>

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

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

setBadgeText()

وعود 
chrome.browserAction.setBadgeText(
  details: object,
  callback?: function,
)

يتم ضبط نص الشارة لإجراء المتصفّح. يتم عرض الشارة في أعلى الرمز.

المعلمات

  • التفاصيل

    كائن

    • tabId

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

      يؤدي هذا الخيار إلى تقييد التغيير إلى وقت اختيار علامة تبويب معيَّنة. تتم إعادة الضبط تلقائيًا عند إغلاق علامة التبويب.

    • text

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

      يمكن تمرير أي عدد من الأحرف، ولكن لا يمكن تضمين سوى أربعة أحرف فقط في المساحة. في حال إدخال سلسلة فارغة ('')، يتم محو نص الشارة. إذا تم تحديد tabId وكان text فارغًا، سيتم محو النص لعلامة التبويب المحدّدة وسيتم ضبطه تلقائيًا على نص الشارة العامة.

  • رد الاتصال

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

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

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

    () => void

المرتجعات

  • وعود <باطلة>

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

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

setIcon()

وعود 
chrome.browserAction.setIcon(
  details: object,
  callback?: function,
)

لضبط الرمز لإجراء المتصفّح. يمكن تحديد الأيقونة كمسار لملف صورة، أو كبيانات البكسل من عنصر لوحة الرسم، أو كقاموس لأحد هذه العناصر. يجب تحديد السمة path أو السمة imageData.

المعلمات

  • التفاصيل

    كائن

    • بيانات الصورة

      ImageData | الكائن اختياري

      عنصر ImageData أو قاموس {size -> ImageData}: تمثل الرمز الذي سيتم تعيينه. إذا تم تحديد الرمز كقاموس، يتم اختيار الصورة المستخدمة بناءً على كثافة وحدات البكسل للشاشة. إذا كان عدد وحدات البكسل التي تناسب وحدة مساحة شاشة واحدة يساوي scale، يتم اختيار صورة بحجم scale * n، حيث يشير n إلى حجم الرمز في واجهة المستخدم. يجب تحديد صورة واحدة على الأقل. يُرجى العِلم أنّ 'details.imageData = foo' مكافئة لـ 'details.imageData = {'16': foo}'

    • المسار

      string | الكائن اختياري

      مسار صورة نسبي أو قاموس {size -> ارتباط صورة path} يشير إلى رمز يتم تعيينه. إذا تم تحديد الرمز كقاموس، يتم اختيار الصورة المستخدمة بناءً على كثافة وحدات البكسل للشاشة. إذا كان عدد وحدات البكسل التي تناسب وحدة مساحة شاشة واحدة يساوي scale، يتم اختيار صورة بحجم scale * n، حيث يشير n إلى حجم الرمز في واجهة المستخدم. يجب تحديد صورة واحدة على الأقل. يُرجى العِلم أنّ 'details.path = foo' يعادل 'details.path = {'16': foo}'

    • tabId

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

      يؤدي هذا الخيار إلى تقييد التغيير إلى وقت اختيار علامة تبويب معيَّنة. تتم إعادة الضبط تلقائيًا عند إغلاق علامة التبويب.

  • رد الاتصال

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

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

    () => void

المرتجعات

  • وعود <باطلة>

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

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

setPopup()

وعود 
chrome.browserAction.setPopup(
  details: object,
  callback?: function,
)

لضبط مستند HTML لفتحه كنافذة منبثقة عندما ينقر المستخدم على رمز إجراء المتصفّح.

المعلمات

  • التفاصيل

    كائن

    • نافذة منبثقة

      سلسلة

      المسار النسبي لملف HTML الذي سيتم عرضه في نافذة منبثقة. وفي حال ضبطها على السلسلة الفارغة ('')، لن تظهر نافذة منبثقة.

    • tabId

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

      يؤدي هذا الخيار إلى تقييد التغيير إلى وقت اختيار علامة تبويب معيَّنة. تتم إعادة الضبط تلقائيًا عند إغلاق علامة التبويب.

  • رد الاتصال

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

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

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

    () => void

المرتجعات

  • وعود <باطلة>

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

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

setTitle()

وعود 
chrome.browserAction.setTitle(
  details: object,
  callback?: function,
)

لضبط عنوان إجراء المتصفّح. يظهر هذا العنوان في التلميح.

المعلمات

  • التفاصيل

    كائن

    • tabId

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

      يؤدي هذا الخيار إلى تقييد التغيير إلى وقت اختيار علامة تبويب معيَّنة. تتم إعادة الضبط تلقائيًا عند إغلاق علامة التبويب.

    • title

      سلسلة

      السلسلة التي يجب أن يعرضها إجراء المتصفح عند تمرير الماوس فوقها.

  • رد الاتصال

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

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

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

    () => void

المرتجعات

  • وعود <باطلة>

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

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

فعاليات

onClicked

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

يتم إطلاقه عند النقر على رمز إجراء في المتصفّح. لا يتم تنشيطه إذا كان إجراء المتصفّح يتضمّن نافذة منبثقة.

المعلمات

  • رد الاتصال

    دالة

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

    (tab: tabs.Tab) => void