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 , או, אם מוגדר מ-רכיב Service Worker של תוסף, אל offscreen קנבס 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);
chrome.action.setIcon({imageData: imageData}, () => { /* ... */ });

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

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

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

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

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

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

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

מצב מופעל

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

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