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 הטעות. עם זאת, אם לא צוין הגודל המדויק, התאמה לעומס (scaling) עלולה לגרום לסמל אובדן פרטים או להיראות מטושטש.

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

הסבר קצר

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

תג

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

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

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

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

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

החזרות

  • הבטחה<Empty>

    Chrome מגרסה 88 ואילך

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

enable()

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

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

פרמטרים

  • tabId

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

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

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

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

    Chrome 67 ואילך

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

    () => void

החזרות

  • הבטחה<Empty>

    Chrome מגרסה 88 ואילך

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

getBadgeBackgroundColor()

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

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

פרמטרים

  • פרטים

    TabDetails

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

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

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

    (result: ColorArray) => void

החזרות

  • Promise&lt;ColorArray&gt;

    Chrome מגרסה 88 ואילך

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

getBadgeText()

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

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

פרמטרים

  • פרטים

    TabDetails

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

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

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

    (result: string) => void

    • תוצאה

      מחרוזת

החזרות

  • Promise&lt;string&gt;

    Chrome מגרסה 88 ואילך

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

getPopup()

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

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

פרמטרים

  • פרטים

    TabDetails

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

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

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

    (result: string) => void

    • תוצאה

      מחרוזת

החזרות

  • Promise&lt;string&gt;

    Chrome מגרסה 88 ואילך

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

getTitle()

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

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

פרמטרים

  • פרטים

    TabDetails

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

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

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

    (result: string) => void

    • תוצאה

      מחרוזת

החזרות

  • Promise&lt;string&gt;

    Chrome מגרסה 88 ואילך

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

setBadgeBackgroundColor()

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

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

פרמטרים

  • פרטים

    אובייקט

    • color [צבע]

      string | ColorArray

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

    • tabId

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

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

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

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

    Chrome 67 ואילך

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

    () => void

החזרות

  • הבטחה<Empty>

    Chrome מגרסה 88 ואילך

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

setBadgeText()

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

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

פרמטרים

  • פרטים

    אובייקט

    • tabId

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

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

    • טקסט

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

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

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

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

    Chrome 67 ואילך

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

    () => void

החזרות

  • הבטחה<Empty>

    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}'

    • נתיב

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

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

    • tabId

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

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

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

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

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

    () => void

החזרות

  • הבטחה<Empty>

    Chrome 116 ואילך

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

setPopup()

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

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

פרמטרים

  • פרטים

    אובייקט

    • פריט קופץ

      מחרוזת

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

    • tabId

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

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

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

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

    Chrome 67 ואילך

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

    () => void

החזרות

  • הבטחה<Empty>

    Chrome מגרסה 88 ואילך

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

setTitle()

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

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

פרמטרים

  • פרטים

    אובייקט

    • tabId

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

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

    • title

      מחרוזת

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

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

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

    Chrome 67 ואילך

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

    () => void

החזרות

  • הבטחה<Empty>

    Chrome מגרסה 88 ואילך

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

אירועים

onClicked

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

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

פרמטרים

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

    פונקציה

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

    (tab: tabs.Tab) => void