chrome.pageAction

refresh date: 2026-09-25 robots: noindex

תיאור

אפשר להשתמש ב-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.5x או 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

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

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

Methods

getPopup()

Promise 
chrome.pageAction.getPopup(
  details: TabDetails,
  callback?: function,
): Promise<string>

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

פרמטרים

  • פרטים

    TabDetails

  • callback

    function optional

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

    (result: string) => void

    • תוצאה

      מחרוזת

החזרות

  • Promise<string>

    ‫Chrome מגרסה 101 ואילך

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

getTitle()

Promise 
chrome.pageAction.getTitle(
  details: TabDetails,
  callback?: function,
): Promise<string>

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

פרמטרים

  • פרטים

    TabDetails

  • callback

    function optional

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

    (result: string) => void

    • תוצאה

      מחרוזת

החזרות

  • Promise<string>

    ‫Chrome מגרסה 101 ואילך

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

hide()

Promise 
chrome.pageAction.hide(
  tabId: number,
  callback?: function,
): Promise<void>

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

פרמטרים

  • tabId

    number

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

  • callback

    function optional

    Chrome 67 ואילך

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

    () => void

החזרות

  • Promise<void>

    ‫Chrome מגרסה 101 ואילך

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

setIcon()

Promise 
chrome.pageAction.setIcon(
  details: object,
  callback?: function,
): Promise<void>

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

פרמטרים

  • פרטים

    אובייקט

    • iconIndex

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

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

    • imageData

      ‫ImageData | object אופציונלי

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

    • נתיב

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

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

    • tabId

      number

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

  • callback

    function optional

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

    () => void

החזרות

  • Promise<void>

    ‫Chrome מגרסה 101 ואילך

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

setPopup()

Promise 
chrome.pageAction.setPopup(
  details: object,
  callback?: function,
): Promise<void>

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

פרמטרים

  • פרטים

    אובייקט

    • פריט קופץ

      מחרוזת

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

    • tabId

      number

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

  • callback

    function optional

    Chrome 67 ואילך

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

    () => void

החזרות

  • Promise<void>

    ‫Chrome מגרסה 101 ואילך

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

setTitle()

Promise 
chrome.pageAction.setTitle(
  details: object,
  callback?: function,
): Promise<void>

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

פרמטרים

  • פרטים

    אובייקט

    • tabId

      number

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

    • title

      מחרוזת

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

  • callback

    function optional

    Chrome 67 ואילך

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

    () => void

החזרות

  • Promise<void>

    ‫Chrome מגרסה 101 ואילך

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

show()

Promise 
chrome.pageAction.show(
  tabId: number,
  callback?: function,
): Promise<void>

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

פרמטרים

  • tabId

    number

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

  • callback

    function optional

    Chrome 67 ואילך

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

    () => void

החזרות

  • Promise<void>

    ‫Chrome מגרסה 101 ואילך

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

אירועים

onClicked

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

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

פרמטרים

  • callback

    פונקציה

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

    (tab: tabs.Tab) => void