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.5 או 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 במניפסט, או קוראים ל-method browserAction.setIcon.

כדי להציג את הסמל בצורה תקינה כשדחיסות הפיקסלים של המסך (יחס size_in_pixel / size_in_dip) שונה מ-1, אפשר להגדיר את הסמל כקבוצת תמונות בגדלים שונים. התמונה שתוצג בפועל תיבחר מתוך הסט כדי להתאים בצורה הטובה ביותר לגודל הפיקסל של 16dip. קבוצת הסמלים יכולה להכיל מפרט של סמלים בכל גודל, ו-Chrome יבחר את הסמל המתאים ביותר.

הסבר קצר

כדי להגדיר את ההסבר הקצר, משתמשים בשדה default_title של default_title במניפסט, או קוראים ל-method browserAction.setTitle. אפשר לציין מחרוזות ספציפיות ללוקאל בשדה default_title. פרטים נוספים זמינים במאמר Internationalization.

תג

בפעולות של הדפדפן אפשר להציג תג – קטע טקסט שמוצג בשכבת-על מעל לסמל. תגים מאפשרים לעדכן בקלות את פעולת הדפדפן ולהציג מעט מידע על מצב התוסף.

השטח של התג מוגבל, ולכן צריך לכלול בו עד 4 תווים.

מגדירים את הטקסט והצבע של התג באמצעות browserAction.setBadgeText ו-browserAction.setBadgeBackgroundColor, בהתאמה.

אם לפעולה בדפדפן יש חלון קופץ, החלון הקופץ מופיע כשהמשתמש לוחץ על סמל התוסף. החלון הקופץ יכול להכיל כל תוכן HTML שתרצו, והגודל שלו מותאם באופן אוטומטי לתוכן. החלון הקופץ לא יכול להיות קטן מ-25x25 ולא יכול להיות גדול מ-800x600.

כדי להוסיף חלון קופץ לפעולה בדפדפן, יוצרים קובץ HTML עם התוכן של החלון הקופץ. מציינים את קובץ ה-HTML בשדה default_popup ב-default_popup במניפסט, או לקרוא ל-method 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

    מספר אופציונלי

    מזהה הכרטיסייה שאת פעולת הדפדפן שלה יש לשנות.

  • קריאה חוזרת (callback)

    פונקציה אופציונלי

    Chrome 67 ומעלה

    הפרמטר callback נראה כך: 

    ()=>void

החזרות

  • Promise<void>

    Chrome 88 ומעלה

    הבטחות נתמכות רק במניפסט מגרסה V3 ואילך. בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callback).

enable()

הבטחה 
chrome.browserAction.enable(
  tabId?: number,
  callback?: function,
)

מפעיל את פעולת הדפדפן בכרטיסייה. ברירת המחדל היא 'מופעל'.

פרמטרים

  • tabId

    מספר אופציונלי

    מזהה הכרטיסייה שאת פעולת הדפדפן שלה יש לשנות.

  • קריאה חוזרת (callback)

    פונקציה אופציונלי

    Chrome 67 ומעלה

    הפרמטר callback נראה כך: 

    ()=>void

החזרות

  • Promise<void>

    Chrome 88 ומעלה

    הבטחות נתמכות רק במניפסט מגרסה V3 ואילך. בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callback).

getBadgeBackgroundColor()

הבטחה 
chrome.browserAction.getBadgeBackgroundColor(
  details: TabDetails,
  callback?: function,
)

מקבל את צבע הרקע של הפעולה בדפדפן.

פרמטרים

  • פרטים

    TabDetails

  • קריאה חוזרת (callback)

    פונקציה אופציונלי

    הפרמטר callback נראה כך: 

    (result: ColorArray)=>void

החזרות

  • Promise<ColorArray>

    Chrome 88 ומעלה

    הבטחות נתמכות רק במניפסט מגרסה V3 ואילך. בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callback).

getBadgeText()

הבטחה 
chrome.browserAction.getBadgeText(
  details: TabDetails,
  callback?: function,
)

מקבל את טקסט התג של הפעולה בדפדפן. אם לא מציינים כרטיסייה, מוחזר טקסט תג שלא קשור לכרטיסייה.

פרמטרים

  • פרטים

    TabDetails

  • קריאה חוזרת (callback)

    פונקציה אופציונלי

    הפרמטר callback נראה כך: 

    (result: string)=>void

    • תוצאה אחת

      מחרוזת

החזרות

  • הבטחה<string>

    Chrome 88 ומעלה

    הבטחות נתמכות רק במניפסט מגרסה V3 ואילך. בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callback).

getPopup()

הבטחה 
chrome.browserAction.getPopup(
  details: TabDetails,
  callback?: function,
)

מקבל את מסמך ה-HTML שמוגדר כחלון הקופץ של פעולת הדפדפן הזו.

פרמטרים

  • פרטים

    TabDetails

  • קריאה חוזרת (callback)

    פונקציה אופציונלי

    הפרמטר callback נראה כך: 

    (result: string)=>void

    • תוצאה אחת

      מחרוזת

החזרות

  • הבטחה<string>

    Chrome 88 ומעלה

    הבטחות נתמכות רק במניפסט מגרסה V3 ואילך. בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callback).

getTitle()

הבטחה 
chrome.browserAction.getTitle(
  details: TabDetails,
  callback?: function,
)

הפונקציה מקבלת את הכותרת של הפעולה בדפדפן.

פרמטרים

  • פרטים

    TabDetails

  • קריאה חוזרת (callback)

    פונקציה אופציונלי

    הפרמטר callback נראה כך: 

    (result: string)=>void

    • תוצאה אחת

      מחרוזת

החזרות

  • הבטחה<string>

    Chrome 88 ומעלה

    הבטחות נתמכות רק במניפסט מגרסה V3 ואילך. בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callback).

setBadgeBackgroundColor()

הבטחה 
chrome.browserAction.setBadgeBackgroundColor(
  details: object,
  callback?: function,
)

הגדרת צבע הרקע של התג.

פרמטרים

  • פרטים

    אובייקט

    • color [צבע]

      מחרוזת|ColorArray

      מערך של ארבעה מספרים שלמים בטווח 0-255 שמרכיבים את צבע ה-RGBA של התג. יכולה להיות גם מחרוזת עם ערך צבע הקסדצימלי של CSS. לדוגמה, #FF0000 או #F00 (אדום). הצגת הצבעים בשקיפות מלאה.

    • tabId

      מספר אופציונלי

      מגביל את השינוי למועד שבו כרטיסייה מסוימת נבחרת. מתאפס באופן אוטומטי כשהכרטיסייה נסגרת.

  • קריאה חוזרת (callback)

    פונקציה אופציונלי

    Chrome 67 ומעלה

    הפרמטר callback נראה כך: 

    ()=>void

החזרות

  • Promise<void>

    Chrome 88 ומעלה

    הבטחות נתמכות רק במניפסט מגרסה V3 ואילך. בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callback).

setBadgeText()

הבטחה 
chrome.browserAction.setBadgeText(
  details: object,
  callback?: function,
)

מגדיר את טקסט התג של פעולת הדפדפן. התג מוצג בחלק העליון של הסמל.

פרמטרים

  • פרטים

    אובייקט

    • tabId

      מספר אופציונלי

      מגביל את השינוי למועד שבו כרטיסייה מסוימת נבחרת. מתאפס באופן אוטומטי כשהכרטיסייה נסגרת.

    • טקסט

      מחרוזת אופציונלי

      אפשר להעביר כל מספר של תווים, אבל רק כארבעה תווים יכולים לעבור ברווח. אם מועברת מחרוזת ריקה (''), הטקסט של התג נמחק. אם מציינים tabId והערך text הוא null, הטקסט בכרטיסייה שצוינה נמחק וברירת המחדל של הטקסט של התג הגלובלי היא אחרת.

  • קריאה חוזרת (callback)

    פונקציה אופציונלי

    Chrome 67 ומעלה

    הפרמטר callback נראה כך: 

    ()=>void

החזרות

  • Promise<void>

    Chrome 88 ומעלה

    הבטחות נתמכות רק במניפסט מגרסה V3 ואילך. בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callback).

setIcon()

הבטחה 
chrome.browserAction.setIcon(
  details: object,
  callback?: function,
)

הגדרת הסמל של פעולת הדפדפן. ניתן לציין את הסמל כנתיב לקובץ תמונה, כנתוני פיקסלים מרכיב של בד ציור, או כמילון של אחד מהסמלים האלה. יש לציין את המאפיין path או את המאפיין imageData.

פרמטרים

  • פרטים

    אובייקט

    • imageData

      ImageData|אובייקט אופציונלי

      אובייקט ImageData או מילון {size -> ImageData} שמייצגים סמל להגדרה. אם הסמל מצוין כמילון, התמונה שתשמש תיבחר בהתאם לדחיסות הפיקסלים של המסך. אם מספר הפיקסלים של התמונה שמתאימים ליחידת שטח אחת הוא scale, נבחרת תמונה בגודל scale * n, כאשר n מייצג את גודל הסמל בממשק המשתמש. יש לציין לפחות תמונה אחת. חשוב לשים לב שהרכיב 'details.imageData = foo' זהה ל-'details.imageData = {'16': foo}'

    • נתיב

      מחרוזת|אובייקט אופציונלי

      נתיב תמונה יחסי או מילון {size ->> image path} שמפנה לסמל שצריך להגדיר. אם הסמל מצוין כמילון, התמונה שתשמש תיבחר בהתאם לדחיסות הפיקסלים של המסך. אם מספר הפיקסלים של התמונה שמתאימים ליחידת שטח אחת הוא scale, נבחרת תמונה בגודל scale * n, כאשר n מייצג את גודל הסמל בממשק המשתמש. יש לציין לפחות תמונה אחת. חשוב לשים לב שהרכיב 'details.path = foo' זהה ל-'details.path = {'16': foo}'

    • tabId

      מספר אופציונלי

      מגביל את השינוי למועד שבו כרטיסייה מסוימת נבחרת. מתאפס באופן אוטומטי כשהכרטיסייה נסגרת.

  • קריאה חוזרת (callback)

    פונקציה אופציונלי

    הפרמטר callback נראה כך: 

    ()=>void

החזרות

  • Promise<void>

    Chrome 116 ומעלה

    הבטחות נתמכות רק במניפסט מגרסה V3 ואילך. בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callback).

setPopup()

הבטחה 
chrome.browserAction.setPopup(
  details: object,
  callback?: function,
)

מגדירה את מסמך ה-HTML להיפתח כחלון קופץ כאשר המשתמש לוחץ על סמל הפעולה בדפדפן.

פרמטרים

  • פרטים

    אובייקט

    • פריט קופץ

      מחרוזת

      הנתיב היחסי לקובץ ה-HTML שיוצג בחלון קופץ. אם הערך מוגדר למחרוזת הריקה (''), לא מוצג חלון קופץ.

    • tabId

      מספר אופציונלי

      מגביל את השינוי למועד שבו כרטיסייה מסוימת נבחרת. מתאפס באופן אוטומטי כשהכרטיסייה נסגרת.

  • קריאה חוזרת (callback)

    פונקציה אופציונלי

    Chrome 67 ומעלה

    הפרמטר callback נראה כך: 

    ()=>void

החזרות

  • Promise<void>

    Chrome 88 ומעלה

    הבטחות נתמכות רק במניפסט מגרסה V3 ואילך. בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callback).

setTitle()

הבטחה 
chrome.browserAction.setTitle(
  details: object,
  callback?: function,
)

מגדיר את הכותרת של פעולת הדפדפן. הכותרת הזו מופיעה בהסבר הקצר.

פרמטרים

  • פרטים

    אובייקט

    • tabId

      מספר אופציונלי

      מגביל את השינוי למועד שבו כרטיסייה מסוימת נבחרת. מתאפס באופן אוטומטי כשהכרטיסייה נסגרת.

    • title

      מחרוזת

      המחרוזת שפעולת הדפדפן צריכה להציג כשמעבירים מעליה את העכבר.

  • קריאה חוזרת (callback)

    פונקציה אופציונלי

    Chrome 67 ומעלה

    הפרמטר callback נראה כך: 

    ()=>void

החזרות

  • Promise<void>

    Chrome 88 ומעלה

    הבטחות נתמכות רק במניפסט מגרסה V3 ואילך. בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callback).

אירועים

onClicked

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

מופעל כשלוחצים על סמל פעולה בדפדפן. לא מופעל אם פעולת הדפדפן כוללת חלון קופץ.

פרמטרים

  • קריאה חוזרת (callback)

    פונקציה

    הפרמטר callback נראה כך: 

    (tab: tabs.Tab)=>void