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

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

نصائح

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

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

أمثلة

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

الأنواع

ColorArray

النوع

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

ImageDataType

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

النوع

ImageData

TabDetails

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

أماكن إقامة

• 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,
)

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

المَعلمات

• التفاصيل

  TabDetails

• معاودة الاتصال

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

  تبدو معلَمة callback على النحو التالي:

  (result: ColorArray)=>void

  • نتيجة

    ColorArray

المرتجعات

• Promise<ColorArray>

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

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

getBadgeText()

وعد

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

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

المَعلمات

• التفاصيل

  TabDetails

• معاودة الاتصال

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

  تبدو معلَمة callback على النحو التالي:

  (result: string)=>void

  • نتيجة

    سلسلة

المرتجعات

• وعد<string>

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

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

getPopup()

وعد

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

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

المَعلمات

• التفاصيل

  TabDetails

• معاودة الاتصال

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

  تبدو معلَمة callback على النحو التالي:

  (result: string)=>void

  • نتيجة

    سلسلة

المرتجعات

• وعد<string>

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

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

getTitle()

وعد

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

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

المَعلمات

• التفاصيل

  TabDetails

• معاودة الاتصال

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

  تبدو معلَمة 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|Object اختياري

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

  • المسار

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

    إما مسار صورة نسبي أو قاموس {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 والإصدارات الأحدث، وتحتاج الأنظمة الأساسية الأخرى إلى استخدام عمليات معاودة الاتصال.

فعاليات

onClicked

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

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

المَعلمات

• معاودة الاتصال

  الوظيفة

  تبدو معلَمة callback على النحو التالي:

  (tab: tabs.Tab)=>void

  • ‏

    tabs.Tab