chrome.action

תיאור

זמינות

מניפסט

כדי להשתמש ב-chrome.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 של תוסף, באמצעות 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);
chrome.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.

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

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

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

חלון קופץ

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

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

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

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

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

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

chrome.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
chrome.action.onClicked.addListener((tab) => {
  chrome.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
chrome.runtime.onInstalled.addListener(() => {
  // Page actions are disabled by default and enabled on select tabs
  chrome.action.disable();

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

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

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

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

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

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

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

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

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

chrome.action.getUserSettings(
  callback?: function,
): Promise<UserSettings>

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

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

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

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

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

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

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

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

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

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