chrome.contextMenus

תיאור

משתמשים ב-chrome.contextMenus API כדי להוסיף פריטים לתפריט ההקשר של Google Chrome. אתם יכולים לבחור לאילו סוגים של אובייקטים יחולו התוספים לתפריט ההקשר, כמו תמונות, היפר-קישורים ודפים.

הרשאות

contextMenus

כדי להשתמש ב-API, צריך להצהיר על ההרשאה "contextMenus" במניפסט של התוסף. בנוסף, צריך לציין סמל בגודל 16x16 פיקסלים שיוצג לצד פריט התפריט. לדוגמה:

{
  "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' שווה לשילוב של כל ההקשרים האחרים, למעט 'launcher'. ההקשר 'מרכז האפליקציות' נתמך רק באפליקציות, והוא משמש להוספת פריטי תפריט לתפריט ההקשר שמופיע כשלוחצים על סמל האפליקציה במרכז האפליקציות, בסרגל המשימות, במזח וכו'. יכול להיות שבפלטפורמות שונות יהיו הגבלות על מה שנתמך בפועל בתפריט ההקשר של מרכז האפליקציות.

Enum

‫"all"

‫"page"

‪"frame"

"selection"

"link"

‎"editable"

"image"

"video"

"audio"

‎"launcher"

‫"browser_action"

‫"page_action"

"action"

CreateProperties

‫Chrome 123 ואילך

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

מאפיינים

  • בוצע סימון

    ‫boolean אופציונלי

    הסטטוס הראשוני של תיבת סימון או כפתור בחירה: true אם נבחר, false אם לא נבחר. אפשר לבחור רק לחצן בחירה אחד בכל פעם בקבוצה נתונה.

  • הקשרים

    [ContextType, ...ContextType[]] optional

    רשימה של הקשרים שבהם יופיע הפריט הזה בתפריט. ברירת המחדל היא ['page'].

  • documentUrlPatterns

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

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

  • פעיל

    ‫boolean אופציונלי

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

  • id [מזהה]

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

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

  • parentId

    string | number optional

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

  • 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.

  • גלוי

    ‫boolean אופציונלי

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

  • onclick

    ‫void אופציונלי

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

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

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

    • מידע

      OnClickData

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

    • כרטיסייה

      Tab

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

ItemType

‫Chrome 44 ואילך

סוג הפריט בתפריט.

Enum

"normal"

‫"checkbox"

"radio"

‎"separator"

OnClickData

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

מאפיינים

  • בוצע סימון

    ‫boolean אופציונלי

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

  • ניתן לעריכה

    בוליאני

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

  • frameId

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

    ‫Chrome 51+‎

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

  • frameUrl

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

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

  • linkUrl

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

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

  • mediaType

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

    אחת מהאפשרויות image,‏ video או audio אם תפריט ההקשר הופעל על אחד מסוגי הרכיבים האלה.

  • menuItemId

    מחרוזת | מספר

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

  • pageUrl

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

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

  • parentMenuItemId

    string | number optional

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

  • selectionText

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

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

  • srcUrl

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

    יופיע ברכיבים עם כתובת URL של 'מקור'.

  • wasChecked

    ‫boolean אופציונלי

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

מאפיינים

ACTION_MENU_TOP_LEVEL_LIMIT

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

ערך

‫6

Methods

create()

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

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

פרמטרים

  • createProperties

    CreateProperties

  • callback

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

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

    () => void

החזרות

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

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

remove()

chrome.contextMenus.remove(
  menuItemId: string | number,
): Promise<void>

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

פרמטרים

  • menuItemId

    מחרוזת | מספר

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

החזרות

  • Promise<void>

    ‫Chrome 123 ואילך

removeAll()

chrome.contextMenus.removeAll(): Promise<void>

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

החזרות

  • Promise<void>

    ‫Chrome 123 ואילך

update()

chrome.contextMenus.update(
  id: string | number,
  updateProperties: object,
): Promise<void>

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

פרמטרים

  • id [מזהה]

    מחרוזת | מספר

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

  • updateProperties

    אובייקט

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

    • בוצע סימון

      ‫boolean אופציונלי

    • הקשרים

      [ContextType, ...ContextType[]] optional

    • documentUrlPatterns

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

    • פעיל

      ‫boolean אופציונלי

    • parentId

      string | number optional

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

    • targetUrlPatterns

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

    • title

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

    • סוג

      ‫ItemType אופציונלי

    • גלוי

      ‫boolean אופציונלי

      ‫Chrome 62 ואילך

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

    • onclick

      ‫void אופציונלי

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

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

      • מידע

        OnClickData

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

        Tab

        ‫Chrome 44 ואילך

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

החזרות

  • Promise<void>

    ‫Chrome 123 ואילך

אירועים

onClicked

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

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

פרמטרים