תיאור
יש להשתמש ב-API chrome.contextMenus
כדי להוסיף פריטים לתפריט ההקשר של Google Chrome. אתם יכולים לבחור את סוגי האובייקטים שעליהם יחולו התוספות לתפריט ההקשר, כמו תמונות, היפר-קישורים ודפים.
הרשאות
contextMenus
כדי להשתמש ב-API, עליך להצהיר על ההרשאה "contextMenus"
במניפסט של התוסף. כמו כן, כדאי לציין סמל בגודל 16 על 16 פיקסלים שיוצג לצד האפשרות בתפריט. למשל:
{
"name": "My extension",
...
"permissions": [
"contextMenus"
],
"icons": {
"16": "icon-bitty.png",
"48": "icon-small.png",
"128": "icon-large.png"
},
...
}
מושגים ושימוש
פריטים בתפריט הקשר יכולים להופיע בכל מסמך (או במסגרת בתוך מסמך), גם באלה עם כתובות URL מסוג file:// או chrome:// . כדי לקבוע באילו מסמכים הפריטים יוכלו להופיע, צריך לציין את השדה documentUrlPatterns
כשמפעילים את השיטה create()
או update()
.
ניתן ליצור כמה פריטים שרוצים בתפריט ההקשר, אבל אם רואים כמה פריטים מהתוסף בו-זמנית, Google Chrome מכווץ אותם אוטומטית לתפריט הורה אחד.
דוגמאות
כדי לנסות את ה-API הזה, התקינו את הדוגמה ל-contextAPI שלcontext מהמאגר chrome-extension-samples.
סוגים
ContextType
ההקשרים השונים שבהם התפריט יכול להופיע. ציון 'all' מקביל לשילוב של כל ההקשרים האחרים, מלבד 'מרכז האפליקציות'. ההקשר של 'מרכז האפליקציות' נתמך רק על ידי אפליקציות, ומשמש להוספת אפשרויות תפריט לתפריט ההקשר שמופיע כשלוחצים על סמל האפליקציה במרכז האפליקציות, בסרגל המשימות, באביזר העגינה וכו'. פלטפורמות שונות עשויות להגביל את מה שנתמך בפועל בתפריט ההקשר של מרכז האפליקציות.
טיפוסים בני מנייה (enum)
"browser_action"
"page_action"
CreateProperties
מאפיינים של הפריט החדש בתפריט ההקשר.
תכונות
-
בוצע סימון
בוליאני אופציונלי
המצב הראשוני של תיבת סימון או לחצן בחירה:
true
לסימון שנבחר,false
אם לא נבחר. ניתן לבחור רק לחצן בחירה אחד בכל פעם בקבוצה נתונה. -
הקשרים
[ContextType, ...ContextType[]] אופציונלי
רשימת ההקשרים שבהם האפשרות הזו תופיע בתפריט. ברירת המחדל היא
['page']
. -
documentUrlPatterns
string[] אופציונלי
מגבילה את הפריט כך שיחול רק על מסמכים או מסגרות שכתובת ה-URL שלהם תואמת לאחת מהתבניות הנתונות. מידע נוסף על פורמטים של תבניות זמין במאמר תבניות התאמה.
-
פעיל
בוליאני אופציונלי
האם האפשרות הזו בתפריט ההקשר מופעלת או מושבתת. ברירת המחדל היא
true
. -
id
מחרוזת אופציונלי
המזהה הייחודי שיש להקצות לפריט הזה. חובה לדפי אירועים. לא יכול להיות זהה למזהה אחר של תוסף זה.
-
parentId
מחרוזת | מספר אופציונלי
המזהה של אפשרות ההורה בתפריט. זה הופך את הפריט לפריט צאצא של פריט שכבר הוספת.
-
targetUrlPatterns
string[] אופציונלי
כמו
documentUrlPatterns
, מסננים שמבוססים על המאפייןsrc
של התגיםimg
,audio
ו-video
ועל המאפייןhref
של תגיa
. -
title
מחרוזת אופציונלי
הטקסט שיוצג בפריט. זהו חובה, אלא אם הערך של
type
הואseparator
. כשההקשר הואselection
, יש להשתמש ב-%s
בתוך המחרוזת כדי להציג את הטקסט שנבחר. לדוגמה, אם הערך של הפרמטר הזה הוא "תרגום של '%s' ל-Pig Latin" והמשתמש בוחר את המילה "cool", האפשרות בתפריט ההקשר היא "תרגום של 'cool' ל-Pig Latin". -
סוג
ItemType אופציונלי
הסוג של האפשרות בתפריט. ברירת המחדל היא
normal
. -
גלוי
בוליאני אופציונלי
האם הפריט מוצג בתפריט.
-
onclick
ביטול אופציונלי
פונקציה שמופעלת חזרה כשלוחצים על האפשרות בתפריט. אפשרות זו לא זמינה בתוך קובץ שירות (service worker). במקום זאת, יש לרשום event listener ל-
contextMenus.onClicked
.הפונקציה
onclick
נראית כך:(info: OnClickData, tab: Tab) => {...}
-
מידע
מידע על הפריט שעליו לחץ המשתמש וההקשר שבו התרחש הקליק.
-
tab
פרטי הכרטיסייה שבה התרחש הקליק. הפרמטר הזה לא קיים באפליקציות פלטפורמה.
-
ItemType
הסוג של האפשרות בתפריט.
טיפוסים בני מנייה (enum)
OnClickData
מידע שנשלח כשלוחצים על פריט בתפריט הקשר.
תכונות
-
בוצע סימון
בוליאני אופציונלי
דגל שמציין את המצב של תיבת סימון או פריט רדיו אחרי שלוחצים עליו.
-
ניתנת לעריכה
boolean
סימון שמציין אם הרכיב ניתן לעריכה (קלט טקסט, אזור טקסט וכו').
-
frameId
מספר אופציונלי
Chrome 51 ומעלההמזהה של המסגרת של האלמנט שבו המשתמש לחץ על תפריט ההקשר, אם הוא היה במסגרת.
-
frameUrl
מחרוזת אופציונלי
כתובת ה-URL של המסגרת של האלמנט שבו בוצעה לחיצה על תפריט ההקשר, אם היא הייתה במסגרת.
-
linkUrl
מחרוזת אופציונלי
אם הרכיב הוא קישור, כתובת ה-URL שאליה הוא מפנה.
-
mediaType
מחרוזת אופציונלי
אחד מהערכים 'תמונה', 'וידאו' או 'אודיו' אם תפריט ההקשר הופעל באחד מסוגי הרכיבים האלה.
-
מחרוזת | מספר
המזהה של האפשרות בתפריט שלחצו עליה.
-
pageUrl
מחרוזת אופציונלי
כתובת ה-URL של הדף שבו בוצעה לחיצה על האפשרות בתפריט. המאפיין הזה לא מוגדר אם הקליק התרחש בהקשר שבו אין דף נוכחי, למשל בתפריט הקשר של מרכז האפליקציות.
-
parentMenuItemId
מחרוזת | מספר אופציונלי
מזהה ההורה, אם קיים, של הפריט שעליו לחץ המשתמש.
-
selectionText
מחרוזת אופציונלי
הטקסט לבחירת ההקשר, אם יש.
-
srcUrl
מחרוזת אופציונלי
תופיע ברכיבים עם כתובת URL מסוג 'src'.
-
wasChecked
בוליאני אופציונלי
דגל שמציין את המצב של תיבת סימון או פריט רדיו לפני הלחיצה עליו.
תכונות
ACTION_MENU_TOP_LEVEL_LIMIT
המספר המקסימלי של פריטי תוסף ברמה העליונה שניתן להוסיף לתפריט הקשר של פעולות בתוסף. המערכת תתעלם מפריטים שחורגים מהמגבלה הזו.
ערך
6
שיטות
create()
chrome.contextMenus.create(
createProperties: CreateProperties,
callback?: function,
)
יצירת אפשרות חדשה בתפריט ההקשר. אם מתרחשת שגיאה במהלך היצירה, יכול להיות שהיא לא תזוהה עד להפעלת הקריאה החוזרת (callback) של היצירה. הפרטים יהיו בruntime.lastError
.
פרמטרים
-
createProperties
-
קריאה חוזרת (callback)
פונקציה אופציונלי
הפרמטר
callback
נראה כך:() => void
החזרות
-
מספר | מחרוזת
המזהה של הפריט החדש שנוצר.
remove()
chrome.contextMenus.remove(
menuItemId: string | number,
callback?: function,
)
מסירה אפשרות של תפריט הקשר.
פרמטרים
-
מחרוזת | מספר
המזהה של האפשרות להסרה בתפריט ההקשר.
-
קריאה חוזרת (callback)
פונקציה אופציונלי
הפרמטר
callback
נראה כך:() => void
החזרות
-
Promise<void>
Chrome מגרסה 123 ואילךיש תמיכה בהבטחות במניפסט מגרסה V3 ואילך, אבל אפשר לבצע קריאה חוזרת (callback) לצורך תאימות לאחור. אי אפשר להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה מסתיימת עם אותו הסוג שמועבר לקריאה החוזרת.
removeAll()
chrome.contextMenus.removeAll(
callback?: function,
)
מסיר את כל הפריטים בתפריט ההקשר שנוספו על ידי התוסף הזה.
פרמטרים
-
קריאה חוזרת (callback)
פונקציה אופציונלי
הפרמטר
callback
נראה כך:() => void
החזרות
-
Promise<void>
Chrome מגרסה 123 ואילךיש תמיכה בהבטחות במניפסט מגרסה V3 ואילך, אבל אפשר לבצע קריאה חוזרת (callback) לצורך תאימות לאחור. אי אפשר להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה מסתיימת עם אותו הסוג שמועבר לקריאה החוזרת.
update()
chrome.contextMenus.update(
id: string | number,
updateProperties: object,
callback?: function,
)
מעדכן פריט של תפריט הקשר שנוצר קודם לכן.
פרמטרים
-
id
מחרוזת | מספר
המזהה של הפריט שצריך לעדכן.
-
updateProperties
אובייקט
המאפיינים שצריך לעדכן. מקבלת את אותם ערכים כמו הפונקציה
contextMenus.create
.-
בוצע סימון
בוליאני אופציונלי
-
הקשרים
[ContextType, ...ContextType[]] אופציונלי
-
documentUrlPatterns
string[] אופציונלי
-
פעיל
בוליאני אופציונלי
-
parentId
מחרוזת | מספר אופציונלי
המזהה של הפריט שיש להפוך להורה של הפריט הזה. הערה: אי אפשר להגדיר פריט כצאצא של עצמו.
-
targetUrlPatterns
string[] אופציונלי
-
title
מחרוזת אופציונלי
-
סוג
ItemType אופציונלי
-
גלוי
בוליאני אופציונלי
Chrome 62 ומעלההאם הפריט מוצג בתפריט.
-
onclick
ביטול אופציונלי
הפונקציה
onclick
נראית כך:(info: OnClickData, tab: Tab) => {...}
-
מידעChrome 44 ואילך
-
tabChrome 44 ואילך
פרטי הכרטיסייה שבה התרחש הקליק. הפרמטר הזה לא קיים באפליקציות פלטפורמה.
-
-
-
קריאה חוזרת (callback)
פונקציה אופציונלי
הפרמטר
callback
נראה כך:() => void
החזרות
-
Promise<void>
Chrome מגרסה 123 ואילךיש תמיכה בהבטחות במניפסט מגרסה V3 ואילך, אבל אפשר לבצע קריאה חוזרת (callback) לצורך תאימות לאחור. אי אפשר להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה מסתיימת עם אותו הסוג שמועבר לקריאה החוזרת.
אירועים
onClicked
chrome.contextMenus.onClicked.addListener(
callback: function,
)
מופעל בעקבות לחיצה על פריט בתפריט הקשר.
פרמטרים
-
קריאה חוזרת (callback)
פונקציה
הפרמטר
callback
נראה כך:(info: OnClickData, tab?: tabs.Tab) => void
-
מידע
-
tab
tabs.Tab אופציונלי
-