chrome.extension

תיאור

ב-API של chrome.extension יש שירותים שאפשר להשתמש בהם בכל דף של תוסף. היא כוללת תמיכה בחילופי הודעות בין תוסף לבין סקריפטים של התוכן שלו, או בין תוספים, כפי שמתואר בפירוט בקטע העברת הודעות.

סוגים

ViewType

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

סוג תצוגת התוסף.

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

"tab"

"popup"

מאפיינים

inIncognitoContext

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

סוג

בוליאני

lastError

≤ MV2 הופסקה השימוש ב-Chrome 58

יש להשתמש ב-runtime.lastError.

מוגדר למשך החיים של קריאה חוזרת (callback) אם קריאה אסינכררונית ל-API של תוסף גרמה לשגיאה. אם לא הייתה שגיאה, הערך של lastError יהיה undefined.

סוג

אובייקט

מאפיינים

  • הודעה

    מחרוזת

    תיאור השגיאה שהתרחשה.

Methods

getBackgroundPage()

חזית בלבד 
chrome.extension.getBackgroundPage()

הפונקציה מחזירה את אובייקט ה-'window' של JavaScript לדף הרקע שפועל בתוך התוסף הנוכחי. הפונקציה מחזירה ערך null אם לסיום אין דף רקע.

החזרות

  • Window | undefined

getExtensionTabs()

≤ MV2 חזית בלבד הוצאה משימוש
chrome.extension.getExtensionTabs(
  windowId?: number,
)

יש להשתמש ב-extension.getViews {type: "tab"}.

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

פרמטרים

  • windowId

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

החזרות

  • Window[]

    מערך של אובייקטי חלונות גלובליים

getURL()

≤ MV2 הופסקה השימוש בהם בגרסה 58 של Chrome
chrome.extension.getURL(
  path: string,
)

יש להשתמש ב-runtime.getURL.

הפונקציה הזו ממירה נתיב יחסי בתוך ספריית ההתקנה של התוסף לכתובת URL מוגדרת במלואה.

פרמטרים

  • נתיב

    מחרוזת

    נתיב למקור מידע בתוך תוסף, ביחס לספריית ההתקנה שלו.

החזרות

  • מחרוזת

    כתובת ה-URL המלאה של המשאב.

getViews()

חזית בלבד 
chrome.extension.getViews(
  fetchProperties?: object,
)

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

פרמטרים

  • fetchProperties

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

    • tabId

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

      Chrome מגרסה 54 ואילך

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

    • סוג

      ViewType אופציונלי

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

    • windowId

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

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

החזרות

  • Window[]

    מערך של אובייקטים גלובליים

isAllowedFileSchemeAccess()

Promise 
chrome.extension.isAllowedFileSchemeAccess(
  callback?: function,
)

אחזור המצב של הגישה של התוסף לסכימה 'file://'. ההגדרה הזו תואמת להגדרה 'התרת גישה לכתובות אתרים של קבצים' לכל תוסף, שבה המשתמש יכול לשלוט דרך הדף chrome://extensions.

פרמטרים

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

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

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

    (isAllowedAccess: boolean) => void

    • isAllowedAccess

      בוליאני

      הערך יהיה TRUE אם הסיומת יכולה לגשת לסכימה 'file://', ו-FALSE במקרה אחר.

החזרות

  • Promise<boolean>

    גרסה 99 ואילך של Chrome

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

isAllowedIncognitoAccess()

Promise 
chrome.extension.isAllowedIncognitoAccess(
  callback?: function,
)

אחזור המצב של הגישה של התוסף למצב פרטי. ההגדרה הזו תואמת להגדרה 'מותר במצב פרטי' שמוגדרת לכל תוסף בנפרד, והמשתמשים יכולים לשנות אותה בדף chrome://extensions.

פרמטרים

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

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

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

    (isAllowedAccess: boolean) => void

    • isAllowedAccess

      בוליאני

      הערך True אם לתוסף יש גישה למצב פרטי, ו-False אחרת.

החזרות

  • Promise<boolean>

    גרסה 99 ואילך של Chrome

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

sendRequest()

Promise &leq; MV2 הוצא משימוש
chrome.extension.sendRequest(
  extensionId?: string,
  request: any,
  callback?: function,
)

יש להשתמש ב-runtime.sendMessage.

שליחת בקשה אחת למאזינים אחרים בתוך התוסף. דומה ל-runtime.connect, אבל שולחת רק בקשה אחת עם תשובה אופציונלית. האירוע extension.onRequest מופעל בכל דף בתוסף.

פרמטרים

  • extensionId

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

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

  • בקשה

    כל

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

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

    גרסה 99 ואילך של Chrome

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

    (response: any) => void

    • תשובה

      כל

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

החזרות

  • Promise<any>

    גרסה 99 ואילך של Chrome

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

setUpdateUrlData()

chrome.extension.setUpdateUrlData(
  data: string,
)

הגדרת הערך של פרמטר ה-CGI של ap שמשמש בכתובת ה-URL לעדכון של התוסף. המערכת מתעלמת מהערך הזה לגבי תוספים שמתארחים בגלריה של התוספים ל-Chrome.

פרמטרים

  • נתונים

    מחרוזת

אירועים

onRequest

&leq; MV2 הוצא משימוש
chrome.extension.onRequest.addListener(
  callback: function,
)

יש להשתמש ב-runtime.onMessage.

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

פרמטרים

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

    פונקציה

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

    (request: any, sender: runtime.MessageSender, sendResponse: function) => void

    • בקשה

      כל

    • sendResponse

      פונקציה

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

      () => void

onRequestExternal

&leq; MV2 הוצא משימוש
chrome.extension.onRequestExternal.addListener(
  callback: function,
)

יש להשתמש ב-runtime.onMessageExternal.

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

פרמטרים

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

    פונקציה

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

    (request: any, sender: runtime.MessageSender, sendResponse: function) => void

    • בקשה

      כל

    • sendResponse

      פונקציה

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

      () => void