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

טיפים

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

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

סוגים

ImageDataType

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

סוג

ImageData

TabDetails

Chrome 88 ומעלה

תכונות

  • tabId

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

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

שיטות

getPopup()

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

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

פרמטרים

  • פרטים

    TabDetails

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

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

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

    (result: string)=>void

    • תוצאה אחת

      מחרוזת

החזרות

  • הבטחה<string>

    Chrome 101 ומעלה

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

getTitle()

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

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

פרמטרים

  • פרטים

    TabDetails

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

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

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

    (result: string)=>void

    • תוצאה אחת

      מחרוזת

החזרות

  • הבטחה<string>

    Chrome 101 ומעלה

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

hide()

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

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

פרמטרים

  • tabId

    מספר

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

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

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

    Chrome 67 ומעלה

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

    ()=>void

החזרות

  • Promise<void>

    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}'

    • נתיב

      מחרוזת|אובייקט אופציונלי

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

    • tabId

      מספר

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

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

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

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

    ()=>void

החזרות

  • Promise<void>

    Chrome 101 ומעלה

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

setPopup()

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

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

פרמטרים

  • פרטים

    אובייקט

    • פריט קופץ

      מחרוזת

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

    • tabId

      מספר

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

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

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

    Chrome 67 ומעלה

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

    ()=>void

החזרות

  • Promise<void>

    Chrome 101 ומעלה

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

setTitle()

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

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

פרמטרים

  • פרטים

    אובייקט

    • tabId

      מספר

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

    • title

      מחרוזת

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

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

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

    Chrome 67 ומעלה

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

    ()=>void

החזרות

  • Promise<void>

    Chrome 101 ומעלה

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

show()

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

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

פרמטרים

  • tabId

    מספר

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

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

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

    Chrome 67 ומעלה

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

    ()=>void

החזרות

  • Promise<void>

    Chrome 101 ומעלה

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

אירועים

onClicked

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

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

פרמטרים

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

    פונקציה

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

    (tab: tabs.Tab)=>void