chrome.contextMenus

refresh date: 2026-09-25 robots: noindex

תיאור

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

הרשאות

contextMenus

שימוש

פריטים בתפריט ההקשר יכולים להופיע בכל מסמך (או מסגרת בתוך מסמך), גם בכאלה עם כתובות URL מסוג file://‎ או chrome:// ‎. כדי לקבוע באילו מסמכים הפריטים יכולים להופיע, צריך לציין את השדה documentUrlPatterns כשקוראים ל-method‏ 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" ו-"tab". ההקשר "מרכז האפליקציות" נתמך רק באפליקציות ומשמש להוספת פריטים לתפריט ההקשר שמופיע כשלוחצים על סמל האפליקציה במרכז האפליקציות, בסרגל המשימות, ב-Dock וכו'. יכול להיות שבפלטפורמות שונות יהיו מגבלות על מה שנתמך בפועל בתפריט ההקשר של מרכז האפליקציות.

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

"all"

"page"

"frame"

"selection"

"link"

"editable"

"image"

"video"

"audio"

"מרכז האפליקציות"

"action"
חל על תפריט ההקשר של פעולת התוסף (הסמל שלו בסרגל הכלים).

"tab"
חל על תפריט ההקשר של כרטיסייה ברצועת הכרטיסיות.

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" והמשתמש בוחר את המילה "cool", הפריט בתפריט ההקשר של הבחירה הוא "Translate 'cool' to Pig Latin".

• סוג

  ItemType אופציונלי

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

• גלוי

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

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

• onclick

  void אופציונלי

  פונקציה שמופעלת כשלוחצים על הפריט בתפריט. האפשרות הזו לא זמינה ב-Service Worker. במקום זאת, צריך לרשום מאזין לאירוע contextMenus.onClicked.

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

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

  • מידע

    OnClickData

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

  • Tab

    כרטיסייה

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

ItemType

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

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

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

"normal"

"checkbox"

"radio"

"separator"

OnClickData

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

מאפיינים

• בוצע סימון

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

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

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

  בוליאני

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

• frameId

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

  Chrome 51 ואילך

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

• frameUrl

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

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

• linkUrl

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

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

• mediaType

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

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

• menuItemId

  מחרוזת | מספר

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

• pageUrl

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

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

• parentMenuItemId

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

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

• selectionText

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

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

• srcUrl

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

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

• wasChecked

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

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

מאפיינים

ACTION_MENU_TOP_LEVEL_LIMIT

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

ערך

6

Methods

create()

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

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

פרמטרים

• createProperties

  CreateProperties

• callback

  function optional

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

  () => void

החזרות

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

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

remove()

Promise

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

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

פרמטרים

• menuItemId

  מחרוזת | מספר

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

• callback

  function optional

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

  () => void

החזרות

• Promise<void>

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

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

  הבטחות נתמכות רק ב-Manifest V3 ואילך, בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callbacks).

removeAll()

Promise

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

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

פרמטרים

• callback

  function optional

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

  () => void

החזרות

• Promise<void>

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

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

  הבטחות נתמכות רק ב-Manifest V3 ואילך, בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callbacks).

update()

Promise

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

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

פרמטרים

• id [מזהה]

  מחרוזת | מספר

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

• updateProperties

  אובייקט

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

  • בוצע סימון

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

  • הקשרים

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

  • documentUrlPatterns

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

  • פעיל

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

  • parentId

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

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

  • targetUrlPatterns

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

  • title

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

  • סוג

    ItemType אופציונלי

  • גלוי

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

    Chrome 62 ואילך

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

  • onclick

    void אופציונלי

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

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

    • מידע

      OnClickData

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

      כרטיסייה

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

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

• callback

  function optional

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

  () => void

החזרות

• Promise<void>

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

  הפעולה מסתיימת כשתפריט ההקשר מתעדכן.

  הבטחות נתמכות רק ב-Manifest V3 ואילך, בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callbacks).

אירועים

onClicked

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

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

פרמטרים

• callback

  פונקציה

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

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

  • מידע

    OnClickData

  • Tab

    tabs.Tab אופציונלי