תיאור
השתמש בפעולות הדפדפן כדי להציב סמלים בסרגל הכלים הראשי של Google Chrome, מימין לסרגל הכתובות. בנוסף לסמל של הפעולה בדפדפן, אפשר לכלול בה הסבר קצר, תג וחלון קופץ.
זמינות
באיור הבא, הסמל של פעולת הדפדפן הוא הריבוע הצבעוני משמאל לסרגל הכתובות. מתחת לסמל מופיע חלון קופץ.
אם רוצים ליצור סמל שלא תמיד פעיל, צריך להשתמש בפעולת דף במקום פעולת דפדפן.
מניפסט
רושמים את פעולת הדפדפן במניפסט התוסף באופן הבא:
{
"name": "My extension",
...
"browser_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
},
...
}
תוכלו להוסיף סמל בכל גודל לשימוש ב-Chrome, ו-Chrome יבחר את הסמל הקרוב ביותר וישנה את גודלו לגודל המתאים כך שימלא את המקום של 16 נקודות. עם זאת, אם לא מציינים את הגודל המדויק, שינוי קנה המידה עלול לגרום לסמל לאבד פרטים או להיראות מעורפל.
מכשירים עם גורמי קנה מידה פחות נפוצים, כמו 1.5 או 1.2x, הופכים להיות יותר נפוצים, ולכן מומלץ לציין כמה גדלים לסמלים. כך אפשר לוודא גם שאם גודל התצוגה של הסמל ישתנה, לא תצטרכו להתאמץ יותר כדי לספק סמלים אחרים.
התחביר הישן לרישום סמל ברירת המחדל עדיין נתמך:
{
"name": "My extension",
...
"browser_action": {
...
"default_icon": "images/icon32.png" // optional
// equivalent to "default_icon": { "32": "images/icon32.png" }
},
...
}
החלקים של ממשק המשתמש
פעולה בדפדפן יכולה לכלול סמל, הסבר קצר, תג וחלון קופץ.
סמל
סמלי הפעולות של הדפדפן ב-Chrome הם 16 נקודות שפל (פיקסלים בלתי תלויים במכשיר) לרוחב ולגובה. סמלים גדולים יותר משתנים בהתאם, אבל לקבלת התוצאות הטובות ביותר כדאי להשתמש בסמל של ריבוע עם 16 נקודות.
ניתן להגדיר את הסמל בשתי דרכים: באמצעות תמונה סטטית או באמצעות רכיב לוח הציור של HTML5. קל יותר להשתמש בתמונות סטטיות באפליקציות פשוטות, אבל אפשר ליצור ממשקי משתמש דינמיים יותר – כמו אנימציה חלקה – באמצעות רכיב הקנבס.
תמונות סטטיות יכולות להיות בכל פורמט ש-WebKit יכול להציג, כולל BMP , GIF , ICO , JPEG או PNG. במקרה של תוספים לא ארוזים, התמונות חייבות להיות בפורמט PNG.
כדי להגדיר את הסמל, משתמשים בשדה default_icon של default_icon במניפסט, או קוראים ל-method browserAction.setIcon
.
כדי להציג את הסמל בצורה תקינה כשדחיסות הפיקסלים של המסך (יחס size_in_pixel / size_in_dip
) שונה מ-1, אפשר להגדיר את הסמל כקבוצת תמונות בגדלים שונים. התמונה שתוצג בפועל תיבחר מתוך הסט כדי להתאים בצורה הטובה ביותר לגודל הפיקסל של 16dip. קבוצת הסמלים יכולה להכיל מפרט של סמלים בכל גודל, ו-Chrome יבחר את הסמל המתאים ביותר.
הסבר קצר
כדי להגדיר את ההסבר הקצר, משתמשים בשדה default_title של default_title במניפסט, או קוראים ל-method browserAction.setTitle
. אפשר לציין מחרוזות ספציפיות ללוקאל בשדה default_title. פרטים נוספים זמינים במאמר Internationalization.
תג
בפעולות של הדפדפן אפשר להציג תג – קטע טקסט שמוצג בשכבת-על מעל לסמל. תגים מאפשרים לעדכן בקלות את פעולת הדפדפן ולהציג מעט מידע על מצב התוסף.
השטח של התג מוגבל, ולכן צריך לכלול בו עד 4 תווים.
מגדירים את הטקסט והצבע של התג באמצעות browserAction.setBadgeText
ו-browserAction.setBadgeBackgroundColor
, בהתאמה.
פריט קופץ
אם לפעולה בדפדפן יש חלון קופץ, החלון הקופץ מופיע כשהמשתמש לוחץ על סמל התוסף. החלון הקופץ יכול להכיל כל תוכן HTML שתרצו, והגודל שלו מותאם באופן אוטומטי לתוכן. החלון הקופץ לא יכול להיות קטן מ-25x25 ולא יכול להיות גדול מ-800x600.
כדי להוסיף חלון קופץ לפעולה בדפדפן, יוצרים קובץ HTML עם התוכן של החלון הקופץ. מציינים את קובץ ה-HTML בשדה default_popup ב-default_popup במניפסט, או לקרוא ל-method browserAction.setPopup
.
טיפים
כדי להשיג את האפקט הוויזואלי הטוב ביותר, מומלץ לפעול לפי ההנחיות הבאות:
- מומלץ להשתמש בפעולות הדפדפן כדי לקבל תכונות שמתאימות לרוב הדפים.
- לא מומלץ להשתמש בפעולות דפדפן לתכונות שמתאימות לדפים מסוימים בלבד. במקום זאת, השתמשו בפעולות בדף.
- מומלץ להשתמש בסמלים גדולים וצבעוניים כדי להפיק את המרב משטח התצוגה בגודל 16x16. סמלי פעולות דפדפן אמורים להיראות קצת יותר גדולים וכבדים מסמלי הפעולות בדף.
- אל תנסה לחקות את סמל התפריט המונוכרומטי של Google Chrome. זה לא עובד טוב עם עיצובים, ובכל מקרה, תוספים צריכים לבלוט קצת.
- מומלץ להשתמש בשקיפות אלפא כדי להוסיף קצוות רכים לסמל. מכיוון שאנשים רבים משתמשים בעיצובים, הסמל שלכם צריך להיראות יפה במגוון של צבעי רקע.
- אל תציגו את הסמל כאנימציה באופן קבוע. זה פשוט מעצבן.
דוגמאות
דוגמאות פשוטות לשימוש בפעולות דפדפן מופיעות בספרייה examples/api/browserAction. בקטע דוגמאות אפשר למצוא דוגמאות נוספות ועזרה בהצגת קוד המקור.
סוגים
ColorArray
סוג
[מספר, מספר, מספר, מספר]
ImageDataType
נתוני פיקסלים של תמונה. חייב להיות אובייקט ImageData. לדוגמה, מרכיב canvas
.
סוג
ImageData
TabDetails
תכונות
-
tabId
מספר אופציונלי
מזהה הכרטיסייה שעבורה יש לבצע שאילתה. אם לא מציינים כרטיסייה, מוחזר המצב הלא ספציפי לכרטיסייה.
שיטות
disable()
chrome.browserAction.disable(
tabId?: number,
callback?: function,
)
משבית את פעולת הדפדפן בכרטיסייה.
פרמטרים
-
tabId
מספר אופציונלי
מזהה הכרטיסייה שאת פעולת הדפדפן שלה יש לשנות.
-
קריאה חוזרת (callback)
פונקציה אופציונלי
Chrome 67 ומעלההפרמטר
callback
נראה כך:() => void
החזרות
-
Promise<void>
Chrome 88 ומעלההבטחות נתמכות רק במניפסט מגרסה V3 ואילך. בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callback).
enable()
chrome.browserAction.enable(
tabId?: number,
callback?: function,
)
מפעיל את פעולת הדפדפן בכרטיסייה. ברירת המחדל היא 'מופעל'.
פרמטרים
-
tabId
מספר אופציונלי
מזהה הכרטיסייה שאת פעולת הדפדפן שלה יש לשנות.
-
קריאה חוזרת (callback)
פונקציה אופציונלי
Chrome 67 ומעלההפרמטר
callback
נראה כך:() => void
החזרות
-
Promise<void>
Chrome 88 ומעלההבטחות נתמכות רק במניפסט מגרסה V3 ואילך. בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callback).
getBadgeBackgroundColor()
chrome.browserAction.getBadgeBackgroundColor(
details: TabDetails,
callback?: function,
)
מקבל את צבע הרקע של הפעולה בדפדפן.
פרמטרים
-
פרטים
-
קריאה חוזרת (callback)
פונקציה אופציונלי
הפרמטר
callback
נראה כך:(result: ColorArray) => void
-
תוצאה אחת
-
החזרות
-
Promise<ColorArray>
Chrome 88 ומעלההבטחות נתמכות רק במניפסט מגרסה V3 ואילך. בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callback).
getBadgeText()
chrome.browserAction.getBadgeText(
details: TabDetails,
callback?: function,
)
מקבל את טקסט התג של הפעולה בדפדפן. אם לא מציינים כרטיסייה, מוחזר טקסט תג שלא קשור לכרטיסייה.
פרמטרים
-
פרטים
-
קריאה חוזרת (callback)
פונקציה אופציונלי
הפרמטר
callback
נראה כך:(result: string) => void
-
תוצאה אחת
string
-
החזרות
-
הבטחה<string>
Chrome 88 ומעלההבטחות נתמכות רק במניפסט מגרסה V3 ואילך. בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callback).
getPopup()
chrome.browserAction.getPopup(
details: TabDetails,
callback?: function,
)
מקבל את מסמך ה-HTML שמוגדר כחלון הקופץ של פעולת הדפדפן הזו.
פרמטרים
-
פרטים
-
קריאה חוזרת (callback)
פונקציה אופציונלי
הפרמטר
callback
נראה כך:(result: string) => void
-
תוצאה אחת
string
-
החזרות
-
הבטחה<string>
Chrome 88 ומעלההבטחות נתמכות רק במניפסט מגרסה V3 ואילך. בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callback).
getTitle()
chrome.browserAction.getTitle(
details: TabDetails,
callback?: function,
)
הפונקציה מקבלת את הכותרת של הפעולה בדפדפן.
פרמטרים
-
פרטים
-
קריאה חוזרת (callback)
פונקציה אופציונלי
הפרמטר
callback
נראה כך:(result: string) => void
-
תוצאה אחת
string
-
החזרות
-
הבטחה<string>
Chrome 88 ומעלההבטחות נתמכות רק במניפסט מגרסה V3 ואילך. בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callback).
setBadgeBackgroundColor()
chrome.browserAction.setBadgeBackgroundColor(
details: object,
callback?: function,
)
הגדרת צבע הרקע של התג.
פרמטרים
-
פרטים
אובייקט
-
color [צבע]
string | ColorArray
מערך של ארבעה מספרים שלמים בטווח 0-255 שמרכיבים את צבע ה-RGBA של התג. יכולה להיות גם מחרוזת עם ערך צבע הקסדצימלי של CSS. לדוגמה,
#FF0000
או#F00
(אדום). הצגת הצבעים בשקיפות מלאה. -
tabId
מספר אופציונלי
מגביל את השינוי למועד שבו כרטיסייה מסוימת נבחרת. מתאפס באופן אוטומטי כשהכרטיסייה נסגרת.
-
-
קריאה חוזרת (callback)
פונקציה אופציונלי
Chrome 67 ומעלההפרמטר
callback
נראה כך:() => void
החזרות
-
Promise<void>
Chrome 88 ומעלההבטחות נתמכות רק במניפסט מגרסה V3 ואילך. בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callback).
setBadgeText()
chrome.browserAction.setBadgeText(
details: object,
callback?: function,
)
מגדיר את טקסט התג של פעולת הדפדפן. התג מוצג בחלק העליון של הסמל.
פרמטרים
-
פרטים
אובייקט
-
tabId
מספר אופציונלי
מגביל את השינוי למועד שבו כרטיסייה מסוימת נבחרת. מתאפס באופן אוטומטי כשהכרטיסייה נסגרת.
-
טקסט
מחרוזת אופציונלי
אפשר להעביר כל מספר של תווים, אבל רק כארבעה תווים יכולים לעבור ברווח. אם מועברת מחרוזת ריקה (
''
), הטקסט של התג נמחק. אם מצייניםtabId
והערךtext
הוא null, הטקסט בכרטיסייה שצוינה נמחק וברירת המחדל של הטקסט של התג הגלובלי היא אחרת.
-
-
קריאה חוזרת (callback)
פונקציה אופציונלי
Chrome 67 ומעלההפרמטר
callback
נראה כך:() => void
החזרות
-
Promise<void>
Chrome 88 ומעלההבטחות נתמכות רק במניפסט מגרסה V3 ואילך. בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callback).
setIcon()
chrome.browserAction.setIcon(
details: object,
callback?: function,
)
הגדרת הסמל של פעולת הדפדפן. ניתן לציין את הסמל כנתיב לקובץ תמונה, כנתוני פיקסלים מרכיב של בד ציור, או כמילון של אחד מהסמלים האלה. יש לציין את המאפיין path
או את המאפיין imageData
.
פרמטרים
-
פרטים
אובייקט
-
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 116 ומעלההבטחות נתמכות רק במניפסט מגרסה V3 ואילך. בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callback).
setPopup()
chrome.browserAction.setPopup(
details: object,
callback?: function,
)
מגדירה את מסמך ה-HTML להיפתח כחלון קופץ כאשר המשתמש לוחץ על סמל הפעולה בדפדפן.
פרמטרים
-
פרטים
אובייקט
-
פריט קופץ
string
הנתיב היחסי לקובץ ה-HTML שיוצג בחלון קופץ. אם הערך מוגדר למחרוזת הריקה (
''
), לא מוצג חלון קופץ. -
tabId
מספר אופציונלי
מגביל את השינוי למועד שבו כרטיסייה מסוימת נבחרת. מתאפס באופן אוטומטי כשהכרטיסייה נסגרת.
-
-
קריאה חוזרת (callback)
פונקציה אופציונלי
Chrome 67 ומעלההפרמטר
callback
נראה כך:() => void
החזרות
-
Promise<void>
Chrome 88 ומעלההבטחות נתמכות רק במניפסט מגרסה V3 ואילך. בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callback).
setTitle()
chrome.browserAction.setTitle(
details: object,
callback?: function,
)
מגדיר את הכותרת של פעולת הדפדפן. הכותרת הזו מופיעה בהסבר הקצר.
פרמטרים
-
פרטים
אובייקט
-
tabId
מספר אופציונלי
מגביל את השינוי למועד שבו כרטיסייה מסוימת נבחרת. מתאפס באופן אוטומטי כשהכרטיסייה נסגרת.
-
title
string
המחרוזת שפעולת הדפדפן צריכה להציג כשמעבירים מעליה את העכבר.
-
-
קריאה חוזרת (callback)
פונקציה אופציונלי
Chrome 67 ומעלההפרמטר
callback
נראה כך:() => void
החזרות
-
Promise<void>
Chrome 88 ומעלההבטחות נתמכות רק במניפסט מגרסה V3 ואילך. בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callback).