browser.action

תיאור

זמינות

מניפסט

כדי להשתמש ב-browser.action API, צריך לציין "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() כדי להגדיר את סמל התוסף באופן פרוגרמטי על ידי ציון נתיב תמונה שונה או על ידי מתן סמל שנוצר באופן דינמי באמצעות רכיב HTML canvas, או, אם ההגדרה מתבצעת מתוך קובץ שירות (service worker) של תוסף, באמצעות offscreen canvas API.

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 פיקסלים.

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

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

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

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

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);
  });
});

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

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

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

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

chrome.action.getBadgeTextColor(
  details: TabDetails,
): Promise<extensionTypes.ColorArray>

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

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

chrome.action.getUserSettings(): Promise<UserSettings>

chrome.action.isEnabled(
  tabId?: number,
): Promise<boolean>

chrome.action.openPopup(
  options?: OpenPopupOptions,
): Promise<void>

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

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

chrome.action.setBadgeTextColor(
  details: object,
): Promise<void>

chrome.action.setIcon(
  details: object,
): Promise<void>

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

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

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

chrome.action.onUserSettingsChanged.addListener(
  callback: function,
)