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 وحدة 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,
)