browser.action

תיאור

אפשר להשתמש ב-API של chrome.action כדי לשלוט בסמל של התוסף בסרגל הכלים של Google Chrome.

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

זמינות

‫Chrome 88 ואילך ‫browser.* ‎ מגרסה Chrome 148 ‫MV3 ואילך

מניפסט

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

"action"

כדי להשתמש ב-API ‏browser.action, צריך לציין "manifest_version" של 3 ולכלול את המפתח "action" בקובץ המניפסט.

{
  "name": "Action Extension",
  ...
  "action": {
    "default_icon": {              // optional
      "16": "images/icon16.png",   // optional
      "24": "images/icon24.png",   // optional
      "32": "images/icon32.png"    // optional
    },
    "default_title": "Click Me",   // optional, shown in tooltip
    "default_popup": "popup.html"  // optional
  },
  ...
}

המפתח "action" (יחד עם הצאצאים שלו) הוא אופציונלי. אם הוא לא נכלל, התוסף עדיין מוצג בסרגל הכלים כדי לספק גישה לתפריט של התוסף. לכן, מומלץ תמיד לכלול לפחות את המפתחות "action" ו-"default_icon".

מושגים ושימוש

חלקים בממשק המשתמש

סמל

הסמל הוא התמונה הראשית בסרגל הכלים של התוסף, והוא מוגדר על ידי המפתח "default_icon" במפתח "action" של המניפסט. הסמלים צריכים להיות בגודל של 16 פיקסלים שאינם תלויים במכשיר (DIP) לרוחב ולגובה.

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

מכשירים עם גורמים פחות נפוצים לקביעת קנה מידה, כמו 1.5x או 1.2x, הופכים לנפוצים יותר, ולכן אנחנו ממליצים לספק כמה גדלים לסמלים. כך גם תבטיחו שהתוסף יתאים לשינויים אפשריים בגודל התצוגה של הסמל בעתיד. עם זאת, אם מספקים רק גודל אחד, אפשר גם להגדיר את המפתח "default_icon" למחרוזת עם הנתיב לסמל יחיד במקום למילון.

אפשר גם להפעיל את action.setIcon() כדי להגדיר את הסמל של התוסף באופן פרוגרמטי. לשם כך, מציינים נתיב אחר לתמונה או מספקים סמל שנוצר באופן דינמי באמצעות רכיב ה-canvas ב-HTML, או, אם ההגדרה מתבצעת מ-Service Worker של תוסף, באמצעות ה-API של offscreen canvas.

const canvas = new OffscreenCanvas(16, 16);
const context = canvas.getContext('2d');
context.clearRect(0, 0, 16, 16);
context.fillStyle = '#00FF00';  // Green
context.fillRect(0, 0, 16, 16);
const imageData = context.getImageData(0, 0, 16, 16);
browser.action.setIcon({imageData: imageData}, () => { /* ... */ });

בתוספים ארוזים (שמותקנים מקובץ ‎ .crx), התמונות יכולות להיות ברוב הפורמטים שמנוע הרינדור Blink יכול להציג, כולל PNG,‏ JPEG,‏ BMP,‏ ICO ועוד. אין תמיכה ב-SVG. בתוספים לא ארוזים צריך להשתמש בתמונות PNG.

הסבר קצר (כותרת)

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

ההגדרה של ברירת המחדל של ההסבר הקצר נקבעת באמצעות השדה "default_title" של המפתח "action" בקובץ manifest.json. אפשר גם להגדיר אותו באופן פרוגרמטי על ידי קריאה ל-action.setTitle().

תג

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

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

browser.action.setBadgeBackgroundColor(
  {color: [0, 255, 0, 0]},  // Green
  () => { /* ... */ },
);

browser.action.setBadgeBackgroundColor(
  {color: '#00FF00'},  // Also green
  () => { /* ... */ },
);

browser.action.setBadgeBackgroundColor(
  {color: 'green'},  // Also, also green
  () => { /* ... */ },
);

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

החלון הקופץ מוגדר בהתחלה על ידי המאפיין "default_popup" במפתח "action" בקובץ manifest.json. אם המאפיין הזה קיים, הוא צריך להצביע על נתיב יחסי בתוך ספריית התוסף. אפשר גם לעדכן אותו באופן דינמי כדי להפנות לנתיב יחסי אחר באמצעות השיטה action.setPopup().

תרחישים לדוגמה

מצב לכל כרטיסייה

לפעולות של תוספים יכולים להיות מצבים שונים בכל כרטיסייה. כדי להגדיר ערך לכרטיסייה ספציפית, משתמשים במאפיין tabId בשיטות ההגדרה של ה-API של action. לדוגמה, כדי להגדיר את טקסט התג לכרטיסייה ספציפית, מבצעים פעולה כמו זו:

function getTabId() { /* ... */}
function getTabBadge() { /* ... */}

browser.action.setBadgeText(
  {
    text: getTabBadge(tabId),
    tabId: getTabId(),
  },
  () => { ... }
);

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

מצב מופעל

כברירת מחדל, הפעולות בסרגל הכלים מופעלות (ניתן ללחוץ עליהן) בכל כרטיסייה. אפשר לשנות את ברירת המחדל הזו על ידי הגדרת המאפיין default_state במפתח action של המניפסט. אם default_state מוגדר כ-"disabled", הפעולה מושבתת כברירת מחדל וצריך להפעיל אותה באופן פרוגרמטי כדי שניתן יהיה ללחוץ עליה. אם default_state מוגדר כ-"enabled" (ברירת המחדל), הפעולה מופעלת וניתן ללחוץ עליה כברירת מחדל.

אפשר לשלוט במצב באופן פרוגרמטי באמצעות ה-methods‏ action.enable() ו-action.disable(). ההגדרה הזו משפיעה רק על השאלה אם החלון הקופץ (אם יש כזה) או האירוע action.onClicked נשלחים לתוסף. היא לא משפיעה על הנוכחות של הפעולה בסרגל הכלים.

דוגמאות

הדוגמאות הבאות ממחישות כמה דרכים נפוצות שבהן משתמשים בפעולות בתוספים. כדי לנסות את ה-API הזה, מתקינים את דוגמת Action API ממאגר chrome-extension-samples.

הצגת חלון קופץ

הרבה פעמים תוספים מציגים חלון קופץ כשהמשתמש לוחץ על הפעולה של התוסף. כדי להטמיע את זה בתוסף שלכם, צריך להצהיר על החלון הקופץ ב-manifest.json ולציין את התוכן ש-Chrome צריך להציג בחלון הקופץ.

// manifest.json
{
  "name": "Action popup demo",
  "version": "1.0",
  "manifest_version": 3,
  "action": {
    "default_title": "Click to view a popup",
    "default_popup": "popup.html"
  }
}
<!-- popup.html -->
<!DOCTYPE html>
<html>
<head>
  <style>
    html {
      min-height: 5em;
      min-width: 10em;
      background: salmon;
    }
  </style>
</head>
<body>
  <p>Hello, world!</p>
</body>
</html>

החדרת סקריפט תוכן בלחיצה

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

// manifest.json
{
  "name": "Action script injection demo",
  "version": "1.0",
  "manifest_version": 3,
  "action": {
    "default_title": "Click to show an alert"
  },
  "permissions": ["activeTab", "scripting"],
  "background": {
    "service_worker": "background.js"
  }
}
// background.js
browser.action.onClicked.addListener((tab) => {
  browser.scripting.executeScript({
    target: {tabId: tab.id},
    files: ['content.js']
  });
});
// content.js
alert('Hello, world!');

הדמיית פעולות באמצעות declarativeContent

בדוגמה הזו אפשר לראות איך הלוגיקה של התוסף ברקע יכולה (א) להשבית פעולה כברירת מחדל ו-(ב) להשתמש ב-declarativeContent כדי להפעיל את הפעולה באתרים ספציפיים.

// service-worker.js

// Wrap in an onInstalled callback to avoid unnecessary work
// every time the service worker is run
browser.runtime.onInstalled.addListener(() => {
  // Page actions are disabled by default and enabled on select tabs
  browser.action.disable();

  // Clear all rules to ensure only our expected rules are set
  browser.declarativeContent.onPageChanged.removeRules(undefined, () => {
    // Declare a rule to enable the action on example.com pages
    let exampleRule = {
      conditions: [
        new browser.declarativeContent.PageStateMatcher({
          pageUrl: {hostSuffix: '.example.com'},
        })
      ],
      actions: [new browser.declarativeContent.ShowAction()],
    };

    // Finally, apply our new array of rules
    let rules = [exampleRule];
    browser.declarativeContent.onPageChanged.addRules(rules);
  });
});

סוגים

OpenPopupOptions

‫Chrome 99 ואילך ‫browser.* ‎ מגרסה 148 של Chrome

מאפיינים

  • windowId

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

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

TabDetails

מאפיינים

  • tabId

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

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

UserSettings

‫Chrome 91 ואילך ‫browser.* ‎ מגרסה 148 של Chrome

אוסף ההגדרות שהמשתמשים קבעו לפעולה של תוסף.

מאפיינים

  • isOnToolbar

    בוליאני

    אם סמל הפעולה של התוסף מוצג בסרגל הכלים ברמה העליונה של חלונות הדפדפן (כלומר, אם המשתמש "הצמיד" את התוסף).

UserSettingsChange

‫Chrome מגרסה 130 ואילך ‫browser.* ‎ מגרסה 148 של Chrome

מאפיינים

  • isOnToolbar

    בוליאני אופציונלי

    אם סמל הפעולה של התוסף מוצג בסרגל הכלים ברמה העליונה של חלונות הדפדפן (כלומר, אם המשתמש "הצמיד" את התוסף).

Methods

disable()

browser.action.disable(
  tabId?: number,
)
: Promise<void>

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

פרמטרים

  • tabId

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

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

החזרות

  • Promise<void>

enable()

browser.action.enable(
  tabId?: number,
)
: Promise<void>

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

פרמטרים

  • tabId

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

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

החזרות

  • Promise<void>

getBadgeBackgroundColor()

browser.action.getBadgeBackgroundColor(
  details: TabDetails,
)
: Promise<extensionTypes.ColorArray>

מחזירה את צבע הרקע של הפעולה.

פרמטרים

החזרות

getBadgeText()

browser.action.getBadgeText(
  details: TabDetails,
)
: Promise<string>

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

פרמטרים

החזרות

  • Promise<string>

getBadgeTextColor()

‫Chrome 110 ואילך ‫browser.* ‎ החל מ-Chrome 148
browser.action.getBadgeTextColor(
  details: TabDetails,
)
: Promise<extensionTypes.ColorArray>

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

פרמטרים

החזרות

getPopup()

browser.action.getPopup(
  details: TabDetails,
)
: Promise<string>

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

פרמטרים

החזרות

  • Promise<string>

getTitle()

browser.action.getTitle(
  details: TabDetails,
)
: Promise<string>

מקבל את שם הפעולה.

פרמטרים

החזרות

  • Promise<string>

getUserSettings()

‫Chrome 91 ואילך ‫browser.* ‎ מגרסה 148 של Chrome
browser.action.getUserSettings(): Promise<UserSettings>

הפונקציה מחזירה את ההגדרות שהמשתמש ציין שקשורות לפעולה של התוסף.

החזרות

isEnabled()

‫Chrome 110 ואילך ‫browser.* ‎ החל מ-Chrome 148
browser.action.isEnabled(
  tabId?: number,
)
: Promise<boolean>

מציין אם פעולת התוסף מופעלת בכרטיסייה (או באופן גלובלי אם לא צוין tabId). פעולות שמופעלות רק באמצעות declarativeContent תמיד מחזירות ערך False.

פרמטרים

  • tabId

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

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

החזרות

  • Promise<boolean>

openPopup()

‫Chrome 127 ואילך browser.* ‎ מגרסת Chrome 148
browser.action.openPopup(
  options?: OpenPopupOptions,
)
: Promise<void>

פתיחת החלון הקופץ של התוסף. בגרסאות Chrome 118 עד Chrome 126, האפשרות הזו זמינה רק לתוספים שמותקנים לפי מדיניות.

פרמטרים

  • אפשרויות

    OpenPopupOptions אופציונלי

    מציין אפשרויות לפתיחת החלון הקופץ.

החזרות

  • Promise<void>

setBadgeBackgroundColor()

browser.action.setBadgeBackgroundColor(
  details: object,
)
: Promise<void>

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

פרמטרים

  • פרטים

    אובייקט

    • צבע

      string | ColorArray

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

    • tabId

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

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

החזרות

  • Promise<void>

setBadgeText()

browser.action.setBadgeText(
  details: object,
)
: Promise<void>

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

פרמטרים

  • פרטים

    אובייקט

    • tabId

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

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

    • text

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

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

החזרות

  • Promise<void>

setBadgeTextColor()

‫Chrome 110 ואילך ‫browser.* ‎ החל מ-Chrome 148
browser.action.setBadgeTextColor(
  details: object,
)
: Promise<void>

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

פרמטרים

  • פרטים

    אובייקט

    • צבע

      string | ColorArray

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

    • tabId

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

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

החזרות

  • Promise<void>

setIcon()

browser.action.setIcon(
  details: object,
)
: 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

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

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

החזרות

  • Promise<void>

    ‫Chrome 96 ואילך ‫browser.* ‎ מגרסה 148 של Chrome

setPopup()

browser.action.setPopup(
  details: object,
)
: Promise<void>

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

פרמטרים

  • פרטים

    אובייקט

    • פריט קופץ

      מחרוזת

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

    • tabId

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

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

החזרות

  • Promise<void>

setTitle()

browser.action.setTitle(
  details: object,
)
: Promise<void>

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

פרמטרים

  • פרטים

    אובייקט

    • tabId

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

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

    • title

      מחרוזת

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

החזרות

  • Promise<void>

אירועים

onClicked

browser.action.onClicked.addListener(
  callback: function,
)

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

פרמטרים

  • callback

    פונקציה

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

    (tab: tabs.Tab) => void

onUserSettingsChanged

‫Chrome מגרסה 130 ואילך ‫browser.* ‎ מגרסה 148 של Chrome
browser.action.onUserSettingsChanged.addListener(
  callback: function,
)

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

פרמטרים