chrome.action

תיאור

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

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

זמינות

Chrome מגרסה 88 ואילך MV3 ואילך

מניפסט

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

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

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

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

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

סוגים

OpenPopupOptions

Chrome מגרסה 99 ואילך

מאפיינים

  • windowId

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

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

TabDetails

מאפיינים

  • tabId

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

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

UserSettings

Chrome מגרסה 91 ואילך

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

מאפיינים

  • isOnToolbar

    בוליאני

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

UserSettingsChange

גרסה 130 ואילך של Chrome

מאפיינים

  • isOnToolbar

    ערך בוליאני אופציונלי

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

שיטות

disable()

מבטיח 
chrome.action.disable(
  tabId?: number,
  callback?: function,
)

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

פרמטרים

  • tabId

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

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

  • קריאה חוזרת (callback)

    פונקציה אופציונלי

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

    () => void

החזרות

  • הבטחה<Empty>

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

enable()

מבטיח 
chrome.action.enable(
  tabId?: number,
  callback?: function,
)

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

פרמטרים

  • tabId

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

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

  • קריאה חוזרת (callback)

    פונקציה אופציונלי

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

    () => void

החזרות

  • הבטחה<Empty>

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

getBadgeBackgroundColor()

מבטיח 
chrome.action.getBadgeBackgroundColor(
  details: TabDetails,
  callback?: function,
)

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

פרמטרים

  • פרטים

    TabDetails

  • קריאה חוזרת (callback)

    פונקציה אופציונלי

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

    (result: ColorArray) => void

החזרות

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

getBadgeText()

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

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

פרמטרים

  • פרטים

    TabDetails

  • קריאה חוזרת (callback)

    פונקציה אופציונלי

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

    (result: string) => void

    • תוצאה

      מחרוזת

החזרות

  • Promise<string>

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

getBadgeTextColor()

Promise Chrome 110+ 
chrome.action.getBadgeTextColor(
  details: TabDetails,
  callback?: function,
)

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

פרמטרים

  • פרטים

    TabDetails

  • קריאה חוזרת (callback)

    פונקציה אופציונלי

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

    (result: ColorArray) => void

החזרות

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

getPopup()

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

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

פרמטרים

  • פרטים

    TabDetails

  • קריאה חוזרת (callback)

    פונקציה אופציונלי

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

    (result: string) => void

    • תוצאה

      מחרוזת

החזרות

  • Promise<string>

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

getTitle()

מבטיח 
chrome.action.getTitle(
  details: TabDetails,
  callback?: function,
)

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

פרמטרים

  • פרטים

    TabDetails

  • קריאה חוזרת (callback)

    פונקציה אופציונלי

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

    (result: string) => void

    • תוצאה

      מחרוזת

החזרות

  • Promise<string>

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

getUserSettings()

Promise Chrome 91+ 
chrome.action.getUserSettings(
  callback?: function,
)

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

פרמטרים

  • קריאה חוזרת (callback)

    פונקציה אופציונלי

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

    (userSettings: UserSettings) => void

החזרות

  • Promise&lt;UserSettings&gt;

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

isEnabled()

Promise גרסה 110 ואילך של Chrome 
chrome.action.isEnabled(
  tabId?: number,
  callback?: function,
)

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

פרמטרים

  • tabId

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

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

  • קריאה חוזרת (callback)

    פונקציה אופציונלי

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

    (isEnabled: boolean) => void

    • isEnabled

      בוליאני

      הערך יהיה True אם פעולת התוסף מופעלת.

החזרות

  • Promise&lt;boolean&gt;

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

openPopup()

Promise Chrome מגרסה 127 ואילך 
chrome.action.openPopup(
  options?: OpenPopupOptions,
  callback?: function,
)

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

פרמטרים

  • אפשרויות

    OpenPopupOptions אופציונלי

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

  • קריאה חוזרת (callback)

    פונקציה אופציונלי

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

    () => void

החזרות

  • הבטחה<Empty>

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

setBadgeBackgroundColor()

מבטיח 
chrome.action.setBadgeBackgroundColor(
  details: object,
  callback?: function,
)

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

פרמטרים

  • פרטים

    אובייקט

    • color [צבע]

      string | ColorArray

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

    • tabId

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

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

  • קריאה חוזרת (callback)

    פונקציה אופציונלי

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

    () => void

החזרות

  • הבטחה<Empty>

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

setBadgeText()

מבטיח 
chrome.action.setBadgeText(
  details: object,
  callback?: function,
)

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

פרמטרים

  • פרטים

    אובייקט

    • tabId

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

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

    • text

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

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

  • קריאה חוזרת (callback)

    פונקציה אופציונלי

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

    () => void

החזרות

  • הבטחה<Empty>

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

setBadgeTextColor()

Promise Chrome 110+ 
chrome.action.setBadgeTextColor(
  details: object,
  callback?: function,
)

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

פרמטרים

  • פרטים

    אובייקט

    • color [צבע]

      string | ColorArray

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

    • tabId

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

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

  • קריאה חוזרת (callback)

    פונקציה אופציונלי

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

    () => void

החזרות

  • הבטחה<Empty>

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

setIcon()

מבטיח 
chrome.action.setIcon(
  details: object,
  callback?: function,
)

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

פרמטרים

  • פרטים

    אובייקט

    • imageData

      ImageData | אובייקט אופציונלי

      אובייקט ImageData או מילון {size -> ImageData} שמייצג את הסמל שיש להגדיר. אם הסמל צוין כמילון, התמונה בפועל שבה נעשה שימוש נבחרת בהתאם לצפיפות הפיקסלים במסך. אם מספר הפיקסלים בתמונה שמתאימים ליחידת שטח אחת במסך שווה ל-scale, תיבחר תמונה בגודל scale * n, כאשר n הוא גודל הסמל בממשק המשתמש. צריך לציין תמונה אחת לפחות. הערה: הביטוי &#39;details.imageData = foo&#39; שווה לביטוי &#39;details.imageData = {&#39;16&#39;: foo}&#39;

    • נתיב

      string | object אופציונלי

      נתיב יחסי של תמונה או מילון {size -&gt; relative image path} שמצביע על הסמל שרוצים להגדיר. אם הסמל מצוין כמילון, התמונה שבה ייעשה שימוש בפועל תיבחר בהתאם לדחיסות הפיקסלים של המסך. אם מספר הפיקסלים של התמונה שמתאימים ליחידה אחת של שטח מסך שווה ל-scale, תיבחר תמונה בגודל scale * n, כאשר n הוא גודל הסמל בממשק המשתמש. צריך לציין לפחות תמונה אחת. הערה: הערך &#39;details.path = foo&#39; שווה ל-&#39;details.path = {&#39;16&#39;: foo}&#39;

    • tabId

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

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

  • קריאה חוזרת (callback)

    פונקציה אופציונלי

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

    () => void

החזרות

  • הבטחה<Empty>

    גרסה 96 ואילך של Chrome

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

setPopup()

מבטיח 
chrome.action.setPopup(
  details: object,
  callback?: function,
)

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

פרמטרים

  • פרטים

    אובייקט

    • פריט קופץ

      מחרוזת

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

    • tabId

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

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

  • קריאה חוזרת (callback)

    פונקציה אופציונלי

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

    () => void

החזרות

  • הבטחה<Empty>

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

setTitle()

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

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

פרמטרים

  • פרטים

    אובייקט

    • tabId

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

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

    • title

      מחרוזת

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

  • קריאה חוזרת (callback)

    פונקציה אופציונלי

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

    () => void

החזרות

  • הבטחה<Empty>

    יש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. לא ניתן להשתמש בשתיהן באותה בקשה להפעלת פונקציה. הפתרון של ההבטחה יהיה באותו סוג שהוענק ל-callback.

אירועים

onClicked

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

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

פרמטרים

  • קריאה חוזרת (callback)

    פונקציה

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

    (tab: tabs.Tab) => void

onUserSettingsChanged

Chrome 130 ואילך 
chrome.action.onUserSettingsChanged.addListener(
  callback: function,
)

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

פרמטרים