chrome.browserAction

תאריך הרענון: 2026-09-25 robots: noindex

תיאור

זמינות

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

אם רוצים ליצור סמל שלא תמיד פעיל, צריך להשתמש בפעולת דף במקום בפעולת דפדפן.

מניפסט

רושמים את פעולת הדפדפן במניפסט התוסף באופן הבא:

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

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

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

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

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

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

הסבר קצר

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

תג

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

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

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

חלון קופץ

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

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

טיפים

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

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