browser.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 הזה. במאמר יצירת תפריט הקשר מוסבר איך משתמשים ב-API.

דוגמאות

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

סוגים

ContextType

Chrome 44 ואילך browser.* ‎ מ-Chrome 148

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

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

"all"

"page"

"frame"

"selection"

"link"

"editable"

"image"

"video"

"audio"

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

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

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

CreateProperties

‫Chrome 123 ואילך ‫browser.* ‎ החל מ-Chrome 148

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

מאפיינים

  • בוצע סימון

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

    המצב הראשוני של תיבת סימון או כפתור בחירה: 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

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

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

ItemType

Chrome 44 ואילך browser.* ‎ מ-Chrome 148

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

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

"normal"

"checkbox"

"radio"

"separator"

OnClickData

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

מאפיינים

  • בוצע סימון

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

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

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

    בוליאני

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

  • frameId

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

    ‫Chrome 51 ואילך ‫browser.* ‎ מגרסת Chrome 148

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

  • 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()

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

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

פרמטרים

  • createProperties

    CreateProperties

  • callback

    function optional

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

    () => void

החזרות

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

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

remove()

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

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

פרמטרים

  • menuItemId

    מחרוזת | מספר

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

החזרות

  • Promise<void>

    ‫Chrome 123 ואילך ‫browser.* ‎ החל מ-Chrome 148

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

removeAll()

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

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

החזרות

  • Promise<void>

    ‫Chrome 123 ואילך ‫browser.* ‎ החל מ-Chrome 148

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

update()

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

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

פרמטרים

  • id [מזהה]

    מחרוזת | מספר

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

  • updateProperties

    אובייקט

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

    • בוצע סימון

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

    • הקשרים

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

    • documentUrlPatterns

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

    • פעיל

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

    • parentId

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

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

    • targetUrlPatterns

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

    • title

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

    • סוג

      ItemType אופציונלי

    • גלוי

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

      ‫Chrome 62 ואילך ‫browser.* ‎ מגרסה 148 של Chrome

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

    • onclick

      void אופציונלי

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

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

      • מידע

        OnClickData

        Chrome 44 ואילך browser.* ‎ מ-Chrome 148
      • Chrome 44 ואילך browser.* ‎ מ-Chrome 148

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

החזרות

  • Promise<void>

    ‫Chrome 123 ואילך ‫browser.* ‎ החל מ-Chrome 148

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

אירועים

onClicked

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

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

פרמטרים