chrome.browserAction

refresh date: 2026-09-25 robots: noindex

الوصف

استخدِم إجراءات المتصفّح لوضع الرموز في شريط أدوات 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 بكسل مستقل عن الجهاز (dip). يتم تغيير حجم الرموز الأكبر لتناسب المساحة المتاحة، ولكن للحصول على أفضل النتائج، استخدِم رمزًا مربّعًا بحجم 16 بكسل مستقل الكثافة.

يمكنك ضبط الرمز بطريقتَين: باستخدام صورة ثابتة أو باستخدام عنصر لوحة الرسم في HTML5. يُعدّ استخدام الصور الثابتة أسهل في التطبيقات البسيطة، ولكن يمكنك إنشاء واجهات مستخدم أكثر ديناميكية، مثل الرسوم المتحركة السلسة، باستخدام عنصر لوحة الرسم.

يمكن أن تكون الصور الثابتة بأي تنسيق يمكن لـ WebKit عرضه، بما في ذلك BMP أو GIF أو ICO أو JPEG أو PNG. بالنسبة إلى الإضافات غير المضغوطة، يجب أن تكون الصور بتنسيق PNG.

لضبط الرمز، استخدِم الحقل default_icon من browser_action في البيان، أو استدعِ الطريقة browserAction.setIcon.

لعرض الرمز بشكل صحيح عندما تكون كثافة بكسل الشاشة (النسبة size_in_pixel / size_in_dip) مختلفة عن 1، يمكن تحديد الرمز كمجموعة من الصور ذات الأحجام المختلفة. سيتم اختيار الصورة الفعلية التي سيتم عرضها من المجموعة لتناسب حجم البكسل الذي يبلغ 16 بكسل مستقل عن الكثافة. يمكن أن تحتوي مجموعة الرموز على أي مواصفات لحجم الرمز، وسيختار Chrome الرمز الأنسب.

تلميح

لضبط تلميح الشاشة، استخدِم الحقل default_title من browser_action في ملف البيان، أو استدعِ الطريقة browserAction.setTitle. يمكنك تحديد سلاسل خاصة باللغة لحقل default_title. يمكنك الاطّلاع على الانتشار على نطاق عالمي للحصول على التفاصيل.

الشارة

يمكن أن تعرض إجراءات المتصفّح شارة اختياريًا، وهي عبارة عن نص صغير يتم وضعه فوق الرمز. تسهّل الشارات تعديل إجراء المتصفّح لعرض قدر صغير من المعلومات حول حالة الإضافة.

بما أنّ مساحة الشارة محدودة، يجب أن تتضمّن 4 أحرف أو أقل.

اضبط نص الشارة ولونها باستخدام browserAction.setBadgeText وbrowserAction.setBadgeBackgroundColor على التوالي.

إذا كان إجراء المتصفّح يتضمّن نافذة منبثقة، ستظهر النافذة المنبثقة عندما ينقر المستخدم على رمز الإضافة. يمكن أن تحتوي النافذة المنبثقة على أي محتوى HTML تريده، ويتم تغيير حجمها تلقائيًا لتناسب محتواها. يجب ألا يقل حجم النافذة المنبثقة عن 25×25 وألا يزيد عن 800×600.

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

نصائح

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

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

أمثلة

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

الأنواع

TabDetails

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

الخصائص

  • tabId

    number اختيارية

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

الطُرق

disable()

Promise 
chrome.browserAction.disable(
  tabId?: number,
  callback?: function,
): Promise<void>

لإيقاف إجراء المتصفّح لعلامة تبويب معيّنة

المعلمات

  • tabId

    number اختيارية

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

  • callback

    function اختياري

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

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

    () => void

المرتجعات

  • وعد<فراغ>

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

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

enable()

Promise 
chrome.browserAction.enable(
  tabId?: number,
  callback?: function,
): Promise<void>

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

المعلمات

  • tabId

    number اختيارية

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

  • callback

    function اختياري

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

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

    () => void

المرتجعات

  • وعد<فراغ>

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

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

getBadgeBackgroundColor()

Promise 
chrome.browserAction.getBadgeBackgroundColor(
  details: TabDetails,
  callback?: function,
): Promise<extensionTypes.ColorArray>

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

المعلمات

  • التفاصيل

    TabDetails

  • callback

    function اختياري

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

    (result: ColorArray) => void

المرتجعات

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

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

getBadgeText()

Promise 
chrome.browserAction.getBadgeText(
  details: TabDetails,
  callback?: function,
): Promise<string>

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

المعلمات

  • التفاصيل

    TabDetails

  • callback

    function اختياري

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

    (result: string) => void

    • نتيجة

      سلسلة

المرتجعات

  • وعد<سلسلة>

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

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

getPopup()

Promise 
chrome.browserAction.getPopup(
  details: TabDetails,
  callback?: function,
): Promise<string>

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

المعلمات

  • التفاصيل

    TabDetails

  • callback

    function اختياري

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

    (result: string) => void

    • نتيجة

      سلسلة

المرتجعات

  • وعد<سلسلة>

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

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

getTitle()

Promise 
chrome.browserAction.getTitle(
  details: TabDetails,
  callback?: function,
): Promise<string>

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

المعلمات

  • التفاصيل

    TabDetails

  • callback

    function اختياري

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

    (result: string) => void

    • نتيجة

      سلسلة

المرتجعات

  • وعد<سلسلة>

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

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

setBadgeBackgroundColor()

Promise 
chrome.browserAction.setBadgeBackgroundColor(
  details: object,
  callback?: function,
): Promise<void>

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

المعلمات

  • التفاصيل

    عنصر

    • اللون

      string | ColorArray

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

    • tabId

      number اختيارية

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

  • callback

    function اختياري

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

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

    () => void

المرتجعات

  • وعد<فراغ>

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

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

setBadgeText()

Promise 
chrome.browserAction.setBadgeText(
  details: object,
  callback?: function,
): Promise<void>

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

المعلمات

  • التفاصيل

    عنصر

    • tabId

      number اختيارية

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

    • نصي

      string اختياري

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

  • callback

    function اختياري

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

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

    () => void

المرتجعات

  • وعد<فراغ>

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

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

setIcon()

Promise 
chrome.browserAction.setIcon(
  details: object,
  callback?: function,
): Promise<void>

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

المعلمات

  • التفاصيل

    عنصر

    • imageData

      ‫ImageData | عنصر اختياري

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

    • المسار

      string | object اختيارية

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

    • tabId

      number اختيارية

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

  • callback

    function اختياري

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

    () => void

المرتجعات

  • وعد<فراغ>

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

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

setPopup()

Promise 
chrome.browserAction.setPopup(
  details: object,
  callback?: function,
): Promise<void>

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

المعلمات

  • التفاصيل

    عنصر

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

      سلسلة

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

    • tabId

      number اختيارية

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

  • callback

    function اختياري

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

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

    () => void

المرتجعات

  • وعد<فراغ>

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

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

setTitle()

Promise 
chrome.browserAction.setTitle(
  details: object,
  callback?: function,
): Promise<void>

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

المعلمات

  • التفاصيل

    عنصر

    • tabId

      number اختيارية

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

    • title

      سلسلة

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

  • callback

    function اختياري

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

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

    () => void

المرتجعات

  • وعد<فراغ>

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

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

الفعاليات

onClicked

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

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

المعلمات

  • callback

    دالة

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

    (tab: tabs.Tab) => void