chrome.action

תיאור

זמינות

מניפסט

כדי להשתמש ב-API chrome.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() כדי להגדיר את סמל התוסף באופן פרוגרמטי על ידי ציון נתיב תמונה אחר או יצירת סמל שנוצר באופן דינמי באמצעות רכיב לוח הציור של HTML, או באמצעות ה-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 color.

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

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

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

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

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

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

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

מצב מופעל

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

דוגמאות

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

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

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

// 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,
)

chrome.action.enable(
  tabId?: number,
  callback?: function,
)

chrome.action.getBadgeBackgroundColor(
  details: TabDetails,
  callback?: function,
)

chrome.action.getBadgeText(
  details: TabDetails,
  callback?: function,
)

chrome.action.getBadgeTextColor(
  details: TabDetails,
  callback?: function,
)

chrome.action.getPopup(
  details: TabDetails,
  callback?: function,
)

chrome.action.getTitle(
  details: TabDetails,
  callback?: function,
)

chrome.action.getUserSettings(
  callback?: function,
)

chrome.action.isEnabled(
  tabId?: number,
  callback?: function,
)

chrome.action.openPopup(
  options?: OpenPopupOptions,
  callback?: function,
)

chrome.action.setBadgeBackgroundColor(
  details: object,
  callback?: function,
)

chrome.action.setBadgeText(
  details: object,
  callback?: function,
)

chrome.action.setBadgeTextColor(
  details: object,
  callback?: function,
)

chrome.action.setIcon(
  details: object,
  callback?: function,
)

chrome.action.setPopup(
  details: object,
  callback?: function,
)

chrome.action.setTitle(
  details: object,
  callback?: function,
)

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