chrome.contextMenus

תיאור

אפשר להשתמש ב-chrome.contextMenus API כדי להוסיף פריטים לתפריט ההקשר של 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 הזה, צריך להתקין את הדוגמה ל-contextMenus API מהמאגר chrome-extension-samples.

סוגים

ContextType

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

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

Enum

"all"

"page"

"frame"

"selection"

"link"

"editable"

"image"

"video"

"audio"

"launcher"

"browser_action"

"page_action"

"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 בתוך המחרוזת כדי להציג את הטקסט שנבחר. לדוגמה, אם הערך של הפרמטר הזה הוא 'Translate '%s' to Pig Latin' (תרגום '%s' ל-Pig Latin) והמשתמש בוחר את המילה 'cool', הפריט בתפריט ההקשר של הבחירה הוא 'Translate 'cool' to Pig Latin' (תרגום 'cool' ל-Pig Latin).

  • סוג

    ItemType אופציונלי

    הסוג של פריט התפריט. ברירת המחדל היא normal.

  • גלוי

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

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

  • onclick

    void optional

    פונקציה שנקראת חזרה כשלוחצים על פריט התפריט. האפשרות הזו לא זמינה בתוך קובץ שירות (service worker). במקום זאת, צריך לרשום מאזין ל-contextMenus.onClicked.

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

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

    • מידע

      OnClickData

      מידע על הפריט שאליו בוצע הקליק ועל ההקשר שבו בוצע הקליק.

    • כרטיסייה

      Tab

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

ItemType

גרסה 44 ואילך של Chrome

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

Enum

"normal"

"checkbox"

"radio"

"separator"

OnClickData

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

מאפיינים

  • בוצע סימון

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

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

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

    boolean

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

  • frameId

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

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

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

  • frameUrl

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

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

  • linkUrl

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

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

  • mediaType

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

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

  • menuItemId

    מחרוזת | מספר

    המזהה של פריט התפריט שעליו לחץ המשתמש.

  • pageUrl

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

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

  • parentMenuItemId

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

    מזהה ההורה, אם יש כזה, של הפריט שעליו לחץ המשתמש.

  • selectionText

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

    הטקסט של בחירת ההקשר, אם יש כזה.

  • srcUrl

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

    יופיע ברכיבים עם כתובת URL מסוג 'src'.

  • wasChecked

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

    סימון שמציין את המצב של תיבת סימון או לחצן בחירה לפני שלחצו עליו.

מאפיינים

ACTION_MENU_TOP_LEVEL_LIMIT

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

ערך

6

Methods

create()

chrome.contextMenus.create(
  createProperties: CreateProperties,
  callback?: function,
)

יצירת פריט חדש בתפריט ההקשר. אם מתרחשת שגיאה במהלך היצירה, יכול להיות שהיא לא תזוהה עד שהקריאה החוזרת (callback) ליצירה תופעל. הפרטים יופיעו ב-runtime.lastError.

פרמטרים

  • createProperties

    CreateProperties

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

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

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

    () => void

החזרות

  • מספר | מחרוזת

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

remove()

Promise 
chrome.contextMenus.remove(
  menuItemId: string | number,
  callback?: function,
)

הסרת פריט מתפריט ההקשר.

פרמטרים

  • menuItemId

    מחרוזת | מספר

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

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

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

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

    () => void

החזרות

  • Promise<void>

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

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

removeAll()

Promise 
chrome.contextMenus.removeAll(
  callback?: function,
)

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

פרמטרים

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

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

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

    () => void

החזרות

  • Promise<void>

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

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

update()

Promise 
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

      void optional

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

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

      • מידע

        OnClickData

        גרסה 44 ואילך של Chrome
      • כרטיסייה

        Tab

        גרסה 44 ואילך של Chrome

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

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

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

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

    () => void

החזרות

  • Promise<void>

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

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

אירועים

onClicked

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

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

פרמטרים

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

    פונקציה

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

    (info: OnClickData, tab?: tabs.Tab) => void