chrome.browserAction

الوصف

مدى التوفّر

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

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

البيان

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

{
  "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 في 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.

نصائح

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

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

أمثلة

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

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

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

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

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

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

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

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

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

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

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

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

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