chrome.browserAction

refresh date: 2026-09-25 robots: noindex

תיאור

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

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

אפשר להגדיר את הסמל בשתי דרכים: באמצעות תמונה סטטית או באמצעות רכיב הקנבס של HTML5. קל יותר להשתמש בתמונות סטטיות באפליקציות פשוטות, אבל אפשר ליצור ממשקי משתמש דינמיים יותר – כמו אנימציה חלקה – באמצעות רכיב ה-canvas.

תמונות סטטיות יכולות להיות בכל פורמט ש-WebKit יכול להציג, כולל BMP,‏ GIF,‏ ICO,‏ JPEG או PNG. בתוספים לא ארוזים, התמונות חייבות להיות בפורמט PNG.

כדי להגדיר את הסמל, משתמשים בשדה default_icon של browser_action במניפסט, או קוראים ל-method‏ browserAction.setIcon.

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

הסבר קצר

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

תג

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

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

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

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

כדי להוסיף חלון קופץ לפעולת הדפדפן, יוצרים קובץ HTML עם התוכן של החלון הקופץ. מציינים את קובץ ה-HTML בשדה default_popup של browser_action במניפסט, או קוראים ל-method‏ browserAction.setPopup.

טיפים

כדי להשיג את ההשפעה החזותית הטובה ביותר, כדאי לפעול לפי ההנחיות הבאות:

  • מומלץ להשתמש בפעולות בדפדפן לתכונות שמתאימות לרוב הדפים.
  • אל תשתמשו בפעולות בדפדפן לתכונות שרלוונטיות רק לכמה דפים. במקום זאת, צריך להשתמש בפעולות בדף.
  • מומלץ להשתמש בסמלים גדולים וצבעוניים שמנצלים את רוב השטח של 16x16 פיקסלים בלתי תלויים במכשיר (dip). סמלי פעולות בדפדפן צריכים להיראות קצת יותר גדולים וכבדים מסמלי פעולות בדף.
  • אל תנסו לחקות את סמל התפריט המונוכרומטי של Google Chrome. זה לא עובד טוב עם עיצובים, ובכל מקרה, התוספים צריכים לבלוט קצת.
  • כן: כדאי להשתמש בשקיפות אלפא כדי להוסיף קצוות רכים לסמל. הרבה אנשים משתמשים בעיצובים, לכן הסמל צריך להיראות טוב על מגוון צבעי רקע.
  • לא מומלץ להשתמש באנימציה בסמל באופן קבוע. זה פשוט מעצבן.

דוגמאות

בספרייה examples/api/browserAction אפשר למצוא דוגמאות פשוטות לשימוש בפעולות בדפדפן. דוגמאות נוספות ועזרה בהצגת קוד המקור זמינות בקטע דוגמאות.

סוגים

TabDetails

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

מאפיינים

  • tabId

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

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

Methods

disable()

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

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

פרמטרים

  • tabId

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

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

  • callback

    function optional

    Chrome 67 ואילך

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

    () => void

החזרות

  • Promise<void>

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

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

enable()

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

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

פרמטרים

  • tabId

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

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

  • callback

    function optional

    Chrome 67 ואילך

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

    () => void

החזרות

  • Promise<void>

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

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

getBadgeBackgroundColor()

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

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

פרמטרים

החזרות

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

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

getBadgeText()

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

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

פרמטרים

  • פרטים

    TabDetails

  • callback

    function optional

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

    (result: string) => void

    • תוצאה

      מחרוזת

החזרות

  • Promise<string>

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

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

getPopup()

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

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

פרמטרים

  • פרטים

    TabDetails

  • callback

    function optional

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

    (result: string) => void

    • תוצאה

      מחרוזת

החזרות

  • Promise<string>

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

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

getTitle()

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

הצגת השם של הפעולה בדפדפן.

פרמטרים

  • פרטים

    TabDetails

  • callback

    function optional

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

    (result: string) => void

    • תוצאה

      מחרוזת

החזרות

  • Promise<string>

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

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

setBadgeBackgroundColor()

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

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

פרמטרים

  • פרטים

    אובייקט

    • צבע

      string | ColorArray

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

    • tabId

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

      השינוי מוגבל למקרים שבהם נבחרת כרטיסייה מסוימת. ההרשאות מתאפסות אוטומטית כשהכרטיסייה נסגרת.

  • callback

    function optional

    Chrome 67 ואילך

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

    () => void

החזרות

  • Promise<void>

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

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

setBadgeText()

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

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

פרמטרים

  • פרטים

    אובייקט

    • tabId

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

      השינוי מוגבל למקרים שבהם נבחרת כרטיסייה מסוימת. ההרשאות מתאפסות אוטומטית כשהכרטיסייה נסגרת.

    • text

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

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

  • callback

    function optional

    Chrome 67 ואילך

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

    () => void

החזרות

  • Promise<void>

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

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

setIcon()

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

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

פרמטרים

  • פרטים

    אובייקט

    • imageData

      ‫ImageData | object אופציונלי

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

    • נתיב

      string | object אופציונלי

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

    • tabId

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

      השינוי מוגבל למקרים שבהם נבחרת כרטיסייה מסוימת. ההרשאות מתאפסות אוטומטית כשהכרטיסייה נסגרת.

  • callback

    function optional

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

    () => void

החזרות

  • Promise<void>

    ‫Chrome מגרסה 116 ואילך

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

setPopup()

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

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

פרמטרים

  • פרטים

    אובייקט

    • פריט קופץ

      מחרוזת

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

    • tabId

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

      השינוי מוגבל למקרים שבהם נבחרת כרטיסייה מסוימת. ההרשאות מתאפסות אוטומטית כשהכרטיסייה נסגרת.

  • callback

    function optional

    Chrome 67 ואילך

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

    () => void

החזרות

  • Promise<void>

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

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

setTitle()

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

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

פרמטרים

  • פרטים

    אובייקט

    • tabId

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

      השינוי מוגבל למקרים שבהם נבחרת כרטיסייה מסוימת. ההרשאות מתאפסות אוטומטית כשהכרטיסייה נסגרת.

    • title

      מחרוזת

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

  • callback

    function optional

    Chrome 67 ואילך

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

    () => void

החזרות

  • Promise<void>

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

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

אירועים

onClicked

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

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

פרמטרים

  • callback

    פונקציה

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

    (tab: tabs.Tab) => void