chrome.contextMenus

תאריך הרענון: 2026-09-25 robots: noindex

תיאור

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

הרשאות

contextMenus

שימוש

פריטים בתפריט ההקשר יכולים להופיע בכל מסמך (או במסגרת בתוך מסמך), גם במסמכים עם כתובות URL מסוג file://‎ או chrome:// ‎. כדי לקבוע באילו מסמכים הפריטים יכולים להופיע, צריך לציין את השדה documentUrlPatterns כשקוראים לשיטה create() או update().

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

מניפסט

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

{
  "name": "My extension",
  ...
  "permissions": [
    "contextMenus"
  ],
  "icons": {
    "16": "icon-bitty.png",
    "48": "icon-small.png",
    "128": "icon-large.png"
  },
  ...
}

דוגמאות

כדי לנסות את ה-API הזה, צריך להתקין את הדוגמה ל-contextMenus API ממאגר chrome-extension-samples.

סוגים

ContextType

‫Chrome 44 ואילך

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

ספירה

‫"all"

‫"page"

‫frame

‫'selection'

‫"link"

‫"editable"

‫"image"

‫'video'

‫"audio"

‫launcher

‫"browser_action"

‫'page_action'

‫'action'

‫'tab'

CreateProperties

‫Chrome 123 ואילך

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

מאפיינים

  • בוצע סימון

    ‫boolean אופציונלי

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

  • contexts

    [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. במקום זאת, צריך לרשום listener ל-contextMenus.onClicked.

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

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

    • מידע

      OnClickData

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

    • Tab

      Tab

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

ItemType

‫Chrome 44 ואילך

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

ספירה

‫'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()

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

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

פרמטרים

  • menuItemId

    מחרוזת | מספר

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

  • callback

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

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

    () => void

החזרות

  • Promise<void>

    ‫Chrome 123 ואילך

    ההבטחה מתקיימת כשתפריט ההקשר מוסר.

    התמיכה ב-Promises קיימת רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.

removeAll()

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

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

פרמטרים

  • callback

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

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

    () => void

החזרות

  • Promise<void>

    ‫Chrome 123 ואילך

    ההבטחה מתקיימת כשההסרה מסתיימת.

    התמיכה ב-Promises קיימת רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.

update()

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

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

פרמטרים

  • id [מזהה]

    מחרוזת | מספר

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

  • updateProperties

    אובייקט

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

    • בוצע סימון

      ‫boolean אופציונלי

    • contexts

      [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

        Tab

        ‫Chrome 44 ואילך

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

  • callback

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

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

    () => void

החזרות

  • Promise<void>

    ‫Chrome 123 ואילך

    ההבטחה מתקיימת כשתפריט ההקשר מתעדכן.

    התמיכה ב-Promises קיימת רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.

אירועים

onClicked

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

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

פרמטרים