chrome.extension

תיאור

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

סוגים

ViewType

‫Chrome 44 ואילך

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

Enum

‫"tab"

‫"popup"

מאפיינים

inIncognitoContext

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

סוג

בוליאני

lastError

‫≤ MV2 הוצא משימוש מאז Chrome 58

צריך להשתמש ב-runtime.lastError.

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

סוג

אובייקט

מאפיינים

  • הודעה

    מחרוזת

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

Methods

getBackgroundPage()

רק בחזית 
chrome.extension.getBackgroundPage(): Window | undefined

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

החזרות

  • חלון | לא מוגדר

getExtensionTabs()

‫≤ MV2 פועל רק ברקע הוצא משימוש
chrome.extension.getExtensionTabs(
  windowId?: number,
): Window[]

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

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

פרמטרים

  • windowId

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

החזרות

  • חלון[]

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

getURL()

‫≤ MV2 הוצא משימוש מאז Chrome 58
chrome.extension.getURL(
  path: string,
): string

צריך להשתמש ב-runtime.getURL.

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

פרמטרים

  • נתיב

    מחרוזת

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

החזרות

  • מחרוזת

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

getViews()

רק בחזית 
chrome.extension.getViews(
  fetchProperties?: object,
): Window[]

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

פרמטרים

  • fetchProperties

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

    • tabId

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

      ‫Chrome 54 ואילך

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

    • סוג

      ‫ViewType אופציונלי

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

    • windowId

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

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

החזרות

  • חלון[]

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

isAllowedFileSchemeAccess()

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

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

פרמטרים

  • callback

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

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

    (isAllowedAccess: boolean) => void

    • isAllowedAccess

      בוליאני

      ‫True אם התוסף יכול לגשת לסכימה file://‎, אחרת False.

החזרות

  • Promise<boolean>

    ‫Chrome 99 ואילך

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

isAllowedIncognitoAccess()

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

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

פרמטרים

  • callback

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

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

    (isAllowedAccess: boolean) => void

    • isAllowedAccess

      בוליאני

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

החזרות

  • Promise<boolean>

    ‫Chrome 99 ואילך

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

sendRequest()

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

צריך להשתמש ב-runtime.sendMessage.

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

פרמטרים

  • extensionId

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

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

  • בקשה

    כל

  • callback

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

    ‫Chrome 99 ואילך

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

    (response: any) => void

    • תשובה

      כל

      אובייקט התגובה ב-JSON שנשלח על ידי ה-handler של הבקשה. אם מתרחשת שגיאה במהלך ההתחברות לתוסף, ההבטחה תידחה.

החזרות

  • Promise<any>

    ‫Chrome 99 ואילך

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

setUpdateUrlData()

chrome.extension.setUpdateUrlData(
  data: string,
): void

מגדיר את הערך של פרמטר ה-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