chrome.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"
  },
  ...
}

מושגים ושימוש

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

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

דוגמאות

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

סוגים

ContextType

Chrome 44 ואילך

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

Enum

"הכול"

"דף"

"מסגרת"

"בחירה"

"link"

"ניתן לעריכה"

"image"

"וידאו"

"audio"

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

"browser_action"

"page_action"

"פעולה"

CreateProperties

Chrome 123 ואילך

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

מאפיינים

  • בוצע סימון

    ערך בוליאני אופציונלי

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

  • ההקשרים

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

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

  • documentUrlPatterns

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

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

  • פעיל

    ערך בוליאני אופציונלי

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

  • id [מזהה]

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

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

  • parentId

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

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

  • targetUrlPatterns

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

    בדומה ל-documentUrlPatterns, מסננים המבוססים על המאפיין src של התגים img, audio ו-video ועל המאפיין href של תגי a.

  • title

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

    הטקסט שיוצג בפריט. הערך הזה חובה, אלא אם הערך של type הוא separator. כאשר ההקשר הוא selection, צריך להשתמש ב-%s בתוך המחרוזת כדי להציג את הטקסט שנבחר. לדוגמה, אם הערך של הפרמטר הזה הוא 'Translate '%s' ללטינית חזירית" והמשתמש בוחר במילה 'מגניב', האפשרות בתפריט ההקשר לבחירה היא 'תרגום 'מגניב' ללטינית חזירית".

  • סוג

    ItemType אופציונלי

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

  • גלוי

    ערך בוליאני אופציונלי

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

  • onclick

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

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

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

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

    • מידע

      OnClickData

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

    • כרטיסייה

      מקש Tab

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

ItemType

Chrome 44 ואילך

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

Enum

"רגיל"

"תיבת סימון"

"רדיו"

"מפריד"

OnClickData

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

מאפיינים

  • בוצע סימון

    ערך בוליאני אופציונלי

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

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

    בוליאני

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

  • frameId

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

    Chrome 51 ואילך

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

  • frameUrl

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

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

  • linkUrl

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

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

  • mediaType

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

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

  • menuItemId

    string | מספר טלפון

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

  • pageUrl

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

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

  • parentMenuItemId

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

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

  • selectionText

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

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

  • srcUrl

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

    הפרמטר הזה יוצג ברכיבים עם 'src' כתובת URL.

  • wasChecked

    ערך בוליאני אופציונלי

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

מאפיינים

ACTION_MENU_TOP_LEVEL_LIMIT

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

ערך

6

שיטות

create()

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

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

פרמטרים

  • createProperties

    CreateProperties

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

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

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

    () => void

החזרות

  • מספר | String (מחרוזת)

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

remove()

הבטחה 
chrome.contextMenus.remove(
  menuItemId: string | number,
  callback?: function,
)

הסרה של אפשרות בתפריט ההקשר.

פרמטרים

  • menuItemId

    string | מספר טלפון

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

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

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

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

    () => void

החזרות

  • הבטחה<Empty>

    Chrome 123 ואילך

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

removeAll()

הבטחה 
chrome.contextMenus.removeAll(
  callback?: function,
)

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

פרמטרים

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

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

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

    () => void

החזרות

  • הבטחה<Empty>

    Chrome 123 ואילך

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

update()

הבטחה 
chrome.contextMenus.update(
  id: string | number,
  updateProperties: object,
  callback?: function,
)

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

פרמטרים

  • id [מזהה]

    string | מספר טלפון

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

  • updateProperties

    אובייקט

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

    • בוצע סימון

      ערך בוליאני אופציונלי

    • ההקשרים

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

    • documentUrlPatterns

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

    • פעיל

      ערך בוליאני אופציונלי

    • parentId

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

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

    • targetUrlPatterns

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

    • title

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

    • סוג

      ItemType אופציונלי

    • גלוי

      ערך בוליאני אופציונלי

      Chrome 62+

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

    • onclick

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

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

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

      • מידע

        OnClickData

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

        מקש Tab

        Chrome 44 ואילך

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

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

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

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

    () => void

החזרות

  • הבטחה<Empty>

    Chrome 123 ואילך

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

אירועים

onClicked

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

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

פרמטרים

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

    פונקציה

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

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