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

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

החזרות

  • Window[]

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

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

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

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

החזרות

  • Window[]

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

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 ואילך

    ההבטחות נתמכות רק ב-Manifest V3 ובגרסאות מאוחרות יותר. בפלטפורמות אחרות צריך להשתמש בפונקציות Callback.

isAllowedIncognitoAccess()

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

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

פרמטרים

  • callback

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

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

    (isAllowedAccess: boolean) => void

    • isAllowedAccess

      בוליאני

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

החזרות

  • Promise<boolean>

    ‫Chrome 99 ואילך

    ההבטחות נתמכות רק ב-Manifest V3 ובגרסאות מאוחרות יותר. בפלטפורמות אחרות צריך להשתמש בפונקציות Callback.

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 של הבקשה. אם מתרחשת שגיאה במהלך ההתחברות לתוסף, הקריאה החוזרת תתבצע ללא ארגומנטים והערך של runtime.lastError יהיה הודעת השגיאה.

החזרות

  • Promise<any>

    ‫Chrome 99 ואילך

    ההבטחות נתמכות רק ב-Manifest V3 ובגרסאות מאוחרות יותר. בפלטפורמות אחרות צריך להשתמש בפונקציות Callback.

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