chrome.pageAction

תיאור

אפשר להשתמש ב-API chrome.pageAction כדי להוסיף סמלים לסרגל הכלים הראשי של Google Chrome, משמאל לסרגל הכתובות. פעולות בדף מייצגות פעולות שניתן לבצע בדף הנוכחי, אבל לא רלוונטיות בכל הדפים. פעולות בדף מופיעות באפור כשהן לא פעילות.

זמינות

≤ MV2

מספר דוגמאות:

  • הרשמה לפיד ה-RSS של הדף הזה
  • יצירת מצגת מהתמונות בדף הזה

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

פעולות מוסתרות בדף מופיעות באפור. לדוגמה, פיד ה-RSS שבהמשך מופיע באפור, כי אי אפשר הרשמה לעדכון של הדף הנוכחי:

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

מניפסט

רושמים את פעולת הדף במניפסט של התוסף באופן הבא:

{
  "name": "My extension",
  ...
  "page_action": {
    "default_icon": {                    // optional
      "16": "images/icon16.png",           // optional
      "24": "images/icon24.png",           // optional
      "32": "images/icon32.png"            // optional
    },
    "default_title": "Google Mail",      // optional; shown in tooltip
    "default_popup": "popup.html"        // optional
  },
  ...
}

מכשירים עם גורמים בקנה מידה פחות נפוץ, כמו פי 1.5 או 1.2x הופכים ליותר נפוצים, לכן מומלץ לספק לסמלים שלכם גדלים שונים. Chrome יבחר את המקור הקרוב ביותר וישנה את קנה המידה שלו כדי למלא את השטח של 16 נקודות. כך אפשר גם להבטיח שאם גודל התצוגה של הסמל ישתנה, לא תצטרכו להשקיע עוד מאמצים כדי לספק סמלים שונים. עם זאת, אם ההבדל בגודל קיצוני מדי, קנה מידה זה עלול לגרום לסמל לאבד את הפרטים או להיראות מטושטש.

התחביר הישן לרישום סמל ברירת המחדל עדיין נתמך:

{
  "name": "My extension",
  ...
  "page_action": {
    ...
    "default_icon": "images/icon32.png"  // optional
    // equivalent to "default_icon": { "32": "images/icon32.png" }
  },
  ...
}

החלקים של ממשק המשתמש

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

לגרום לפעולת דף להופיע ומופיעה באפור באמצעות pageAction.show וגם pageAction.hide methods, בהתאמה. כברירת מחדל, פעולה בדף מופיעה באפור. אחרי ש להציג אותו, מציינים את הכרטיסייה שבה הסמל יופיע. הסמל נשאר גלוי עד שהכרטיסייה נסגר או מתחיל להציג כתובת URL שונה (למשל, מפני שהמשתמש לוחץ על קישור).

טיפים

כדי להשיג את ההשפעה החזותית הטובה ביותר, מומלץ לפעול לפי ההנחיות הבאות:

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

סוגים

ImageDataType

נתוני פיקסלים של תמונה. חייב להיות אובייקט ImageData (לדוגמה, מרכיב canvas).

סוג

ImageData

TabDetails

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

מאפיינים

  • tabId

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

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

שיטות

getPopup()

הבטחה 
chrome.pageAction.getPopup(
  details: TabDetails,
  callback?: function,
)

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

פרמטרים

  • פרטים

    TabDetails

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

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

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

    (result: string) => void

    • תוצאה

      מחרוזת

החזרות

  • Promise<string>

    Chrome 101 ואילך

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

getTitle()

הבטחה 
chrome.pageAction.getTitle(
  details: TabDetails,
  callback?: function,
)

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

פרמטרים

  • פרטים

    TabDetails

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

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

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

    (result: string) => void

    • תוצאה

      מחרוזת

החזרות

  • Promise<string>

    Chrome 101 ואילך

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

hide()

הבטחה 
chrome.pageAction.hide(
  tabId: number,
  callback?: function,
)

הסתרת פעולת הדף. פעולות מוסתרות בדף עדיין מופיעות בסרגל הכלים של Chrome, אבל הן מופיעות באפור.

פרמטרים

  • tabId

    number

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

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

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

    Chrome 67 ואילך

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

    () => void

החזרות

  • הבטחה<Empty>

    Chrome 101 ואילך

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

setIcon()

הבטחה 
chrome.pageAction.setIcon(
  details: object,
  callback?: function,
)

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

פרמטרים

  • פרטים

    אובייקט

    • iconIndex

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

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

    • imageData

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

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

    • נתיב

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

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

    • tabId

      number

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

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

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

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

    () => void

החזרות

  • הבטחה<Empty>

    Chrome 101 ואילך

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

setPopup()

הבטחה 
chrome.pageAction.setPopup(
  details: object,
  callback?: function,
)

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

פרמטרים

  • פרטים

    אובייקט

    • פריט קופץ

      מחרוזת

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

    • tabId

      number

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

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

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

    Chrome 67 ואילך

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

    () => void

החזרות

  • הבטחה<Empty>

    Chrome 101 ואילך

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

setTitle()

הבטחה 
chrome.pageAction.setTitle(
  details: object,
  callback?: function,
)

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

פרמטרים

  • פרטים

    אובייקט

    • tabId

      number

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

    • title

      מחרוזת

      מחרוזת ההסבר הקצר.

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

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

    Chrome 67 ואילך

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

    () => void

החזרות

  • הבטחה<Empty>

    Chrome 101 ואילך

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

show()

הבטחה 
chrome.pageAction.show(
  tabId: number,
  callback?: function,
)

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

פרמטרים

  • tabId

    number

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

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

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

    Chrome 67 ואילך

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

    () => void

החזרות

  • הבטחה<Empty>

    Chrome 101 ואילך

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

אירועים

onClicked

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

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

פרמטרים

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

    פונקציה

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

    (tab: tabs.Tab) => void