chrome.contextMenus

תיאור

יש להשתמש ב-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

Chrome 44 ואילך

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

טיפוסים בני מנייה (enum)

"browser_action"

"page_action"

CreateProperties

Chrome מגרסה 123 ואילך

מאפיינים של הפריט החדש בתפריט ההקשר.

תכונות

  • בוצע סימון

    בוליאני אופציונלי

    המצב הראשוני של תיבת סימון או לחצן בחירה: 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)=> {...}

    • מידע

      OnClickData

      מידע על הפריט שעליו לחץ המשתמש וההקשר שבו התרחש הקליק.

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

ItemType

Chrome 44 ואילך

הסוג של האפשרות בתפריט.

טיפוסים בני מנייה (enum)

OnClickData

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

תכונות

  • בוצע סימון

    בוליאני אופציונלי

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

  • ניתנת לעריכה

    boolean

    סימון שמציין אם הרכיב ניתן לעריכה (קלט טקסט, אזור טקסט וכו').

  • frameId

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

    Chrome 51 ומעלה

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

  • frameUrl

    מחרוזת אופציונלי

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

  • linkUrl

    מחרוזת אופציונלי

    אם הרכיב הוא קישור, כתובת ה-URL שאליה הוא מפנה.

  • mediaType

    מחרוזת אופציונלי

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

  • menuItemId

    string|number

    המזהה של האפשרות בתפריט שלחצו עליה.

  • 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

    CreateProperties

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

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

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

    ()=>void

החזרות

  • number|string

    המזהה של הפריט החדש שנוצר.

remove()

הבטחה 
chrome.contextMenus.remove(
  menuItemId: string|number,
  callback?: function,
)

מסירה אפשרות של תפריט הקשר.

פרמטרים

  • menuItemId

    string|number

    המזהה של האפשרות להסרה בתפריט ההקשר.

  • קריאה חוזרת (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

    string|number

    המזהה של הפריט שצריך לעדכן.

  • updateProperties

    אובייקט

    המאפיינים שצריך לעדכן. מקבלת את אותם ערכים כמו הפונקציה contextMenus.create.

    • בוצע סימון

      בוליאני אופציונלי

    • הקשרים

      [ContextType,...ContextType[]] אופציונלי

    • documentUrlPatterns

      string[] אופציונלי

    • פעיל

      בוליאני אופציונלי

    • parentId

      מחרוזת|מספר אופציונלי

      המזהה של הפריט שיש להפוך להורה של הפריט הזה. הערה: אי אפשר להגדיר פריט כצאצא של עצמו.

    • targetUrlPatterns

      string[] אופציונלי

    • title

      מחרוזת אופציונלי

    • סוג

      ItemType אופציונלי

    • גלוי

      בוליאני אופציונלי

      Chrome 62 ומעלה

      האם הפריט מוצג בתפריט.

    • onclick

      ביטול אופציונלי

      הפונקציה onclick נראית כך: 

      (info: OnClickData,tab: Tab)=> {...}

      • מידע

        OnClickData

        Chrome 44 ואילך
      • Chrome 44 ואילך

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

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

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

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

    ()=>void

החזרות

  • Promise<void>

    Chrome מגרסה 123 ואילך

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

אירועים

onClicked

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

מופעל בעקבות לחיצה על פריט בתפריט הקשר.

פרמטרים