chrome.browserAction

refresh date: 2026-09-25 robots: noindex

الوصف

مدى التوفّر

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

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

البيان

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

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

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

نصائح

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

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

أمثلة

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

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

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

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

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

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

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

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

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

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

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

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

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