chrome.pageAction

תאריך הרענון: 2026-09-25 robots: noindex

תיאור

אפשר להשתמש ב-chrome.pageAction API כדי להוסיף סמלים לסרגל הכלים הראשי של 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 יבחר את האפשרות הכי קרובה וישנה את הגודל שלה כדי שתתאים למרחב של 16dip. בנוסף, אם גודל התצוגה של הסמל ישתנה, לא תצטרכו לעשות שום דבר כדי לספק סמלים שונים. עם זאת, אם ההבדל בגודל קיצוני מדי, יכול להיות שהשינוי הזה יגרום לאיבוד פרטים בסמל או שהוא ייראה מטושטש.

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

{
  "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

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

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

    (result: string) => void

    • תוצאה

      מחרוזת

החזרות

  • Promise<string>

    ‫Chrome 101 ואילך

    התמיכה ב-Promises קיימת רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.

getTitle()

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

מחזירה את הכותרת של פעולת הדף.

פרמטרים

  • פרטים

    TabDetails

  • callback

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

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

    (result: string) => void

    • תוצאה

      מחרוזת

החזרות

  • Promise<string>

    ‫Chrome 101 ואילך

    התמיכה ב-Promises קיימת רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.

hide()

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

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

פרמטרים

  • tabId

    number

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

  • callback

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

    ‫Chrome 67 ואילך

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

    () => void

החזרות

  • Promise<void>

    ‫Chrome 101 ואילך

    התמיכה ב-Promises קיימת רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.

setIcon()

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

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

פרמטרים

  • פרטים

    אובייקט

    • iconIndex

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

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

    • imageData

      ImageData | object optional

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

    • נתיב

      string | object optional

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

    • tabId

      number

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

  • callback

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

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

    () => void

החזרות

  • Promise<void>

    ‫Chrome 101 ואילך

    התמיכה ב-Promises קיימת רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.

setPopup()

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

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

פרמטרים

  • פרטים

    אובייקט

    • חלון קופץ

      מחרוזת

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

    • tabId

      number

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

  • callback

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

    ‫Chrome 67 ואילך

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

    () => void

החזרות

  • Promise<void>

    ‫Chrome 101 ואילך

    התמיכה ב-Promises קיימת רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.

setTitle()

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

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

פרמטרים

  • פרטים

    אובייקט

    • tabId

      number

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

    • title

      מחרוזת

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

  • callback

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

    ‫Chrome 67 ואילך

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

    () => void

החזרות

  • Promise<void>

    ‫Chrome 101 ואילך

    התמיכה ב-Promises קיימת רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.

show()

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

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

פרמטרים

  • tabId

    number

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

  • callback

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

    ‫Chrome 67 ואילך

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

    () => void

החזרות

  • Promise<void>

    ‫Chrome 101 ואילך

    התמיכה ב-Promises קיימת רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.

אירועים

onClicked

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

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

פרמטרים

  • callback

    פונקציה

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

    (tab: tabs.Tab) => void