chrome.runtime

תיאור

משתמשים ב-chrome.runtime API כדי לאחזר את ה-service worker, להחזיר פרטים על המניפסט ולהקשיב לאירועים במחזור החיים של התוסף ולהגיב להם. אפשר גם להשתמש ב-API הזה כדי להמיר את הנתיב היחסי של כתובות URL לכתובות URL מלאות.

רוב הממשקים של ה-API הזה לא דורשים הרשאות כלשהן. ההרשאה הזו נדרשת ל-connectNative(), ל-sendNativeMessage() ול-onNativeConnect.

בדוגמה הבאה מוסבר איך להצהיר על ההרשאה "nativeMessaging" במניפסט:

manifest.json:

{
  "name": "My extension",
  ...
  "permissions": [
    "nativeMessaging"
  ],
  ...
}

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

ב-Runtime API יש שיטות לתמיכה במספר תחומים שבהם התוספים שלכם יכולים להשתמש:

העברת הודעות
התוסף יכול לתקשר עם הקשרים שונים בתוך התוסף וגם עם תוספים אחרים באמצעות השיטות והאירועים הבאים: connect(), onConnect, onConnectExternal, sendMessage(), onMessage וגם onMessageExternal. בנוסף, התוסף יכול להעביר הודעות לאפליקציות מקוריות במכשיר של המשתמש באמצעות connectNative() ו-sendNativeMessage().
גישה למטא-נתונים של תוספים ופלטפורמות
השיטות האלה מאפשרות לאחזר כמה קטעי מטא-נתונים ספציפיים לגבי התוסף והפלטפורמה. שיטות בקטגוריה הזו כוללות את getManifest() ואת getPlatformInfo().
ניהול מחזור החיים והאפשרויות של התוספים
המאפיינים האלה מאפשרים לבצע פעולות מטא מסוימות על התוסף ולהציג את דף האפשרויות. שיטות ואירועים בקטגוריה הזו כוללים את onInstalled,‏ onStartup,‏ openOptionsPage(),‏ reload(),‏ requestUpdateCheck() ו-setUninstallURL().
כלי עזר
השיטות האלה מספקות שימושים שונים, כמו המרה של ייצוגים פנימיים של משאבים לפורמטים חיצוניים. שיטות בקטגוריה הזו כוללות את getURL().
כלי עזר במצב קיוסק
השיטות האלה זמינות רק ב-ChromeOS, והן נועדו בעיקר לתמוך בהטמעות של קיוסקים. שיטות בקטגוריה הזו כוללות את restart() ואת restartAfterDelay()`.

התנהגות של תוסף לא ארוז

כשמטענים מחדש תוסף לא ארוז, המערכת מתייחסת לכך כאל עדכון. המשמעות היא שהאירוע chrome.runtime.onInstalled יופעל עם הסיבה "update". הנתון הזה כולל גם את הפעמים שבהן התוסף נטען מחדש באמצעות chrome.runtime.reload().

תרחישים לדוגמה

הוספת תמונה לדף אינטרנט

כדי שדף אינטרנט יוכל לגשת לנכס שמתארח בדומיין אחר, צריך לציין את כתובת ה-URL המלאה של המשאב (למשל, <img src="https://example.com/logo.png">). אותו הדבר נכון לגבי הכללת נכס תוסף בדף אינטרנט. שני ההבדלים הם שנכסי התוסף חייבים להיות חשופים כמשאבים שניתנים לגישה באינטרנט, ובדרך כלל סקריפטים של תוכן אחראים להחדרת נכסי התוסף.

בדוגמה הזו, התוסף יוסיף את logo.png לדף שאליו מוזרק סקריפט התוכן, באמצעות runtime.getURL() כדי ליצור כתובת URL מלאה. אבל קודם צריך להצהיר על הנכס כמשאב שגלוי באינטרנט במניפסט.

manifest.json:

{
  ...
  "web_accessible_resources": [
    {
      "resources": [ "logo.png" ],
      "matches": [ "https://*/*" ]
    }
  ],
  ...
}

content.js:

{ // Block used to avoid setting global variables
  const img = document.createElement('img');
  img.src = chrome.runtime.getURL('logo.png');
  document.body.append(img);
}

שליחת נתונים מסקריפט תוכן ל-service worker

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

בדוגמה הזו, סקריפט התוכן צריך נתונים מסוימים מה-service worker של התוסף כדי לאתחל את ממשק המשתמש שלו. כדי לקבל את הנתונים האלה, הוא מעביר את ההודעה get-user-data שהוגדרה על ידי המפתח ל-service worker, והוא משיב עם עותק של פרטי המשתמש.

content.js:

// 1. Send a message to the service worker requesting the user's data
chrome.runtime.sendMessage('get-user-data', (response) => {
  // 3. Got an asynchronous response with the data from the service worker
  console.log('received user data', response);
  initializeUI(response);
});

service-worker.js:

// Example of a simple user data object
const user = {
  username: 'demo-user'
};

chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  // 2. A page requested user data, respond with a copy of `user`
  if (message === 'get-user-data') {
    sendResponse(user);
  }
});

איסוף משוב על ביטול ההתקנה

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

background.js:

chrome.runtime.onInstalled.addListener(details => {
  if (details.reason === chrome.runtime.OnInstalledReason.INSTALL) {
    chrome.runtime.setUninstallURL('https://example.com/extension-survey');
  }
});

דוגמאות

דוגמאות נוספות לממשקי API בסביבת זמן ריצה מפורטות בהדגמה של Manifest V3 – משאבים שניתנים לגישה באינטרנט.

סוגים

ContextFilter

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

מסנן להתאמה להקשרים מסוימים של תוספים. הקשרים התואמים חייבים להתאים לכל המסננים שצוינו. כל מסנן שלא צוין תואם לכל ההקשרים הזמינים. לכן, מסנן של ‎{}‎ יתאים לכל ההקשרים הזמינים.

מאפיינים

  • contextIds

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

  • contextTypes

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

  • documentIds

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

  • documentOrigins

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

  • documentUrls

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

  • frameIds

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

  • מצב פרטי

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

  • tabIds

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

  • windowIds

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

ContextType

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

Enum

"TAB"
ציון סוג ההקשר ככרטיסייה

'POPUP'
מציין את סוג ההקשר כחלון קופץ של תוסף

'BACKGROUND'
מציין את סוג ההקשר כ-service worker.

"OFFSCREEN_DOCUMENT"
הערך הזה מציין שסוג ההקשר הוא מסמך מחוץ למסך.

"SIDE_PANEL"
הגדרת סוג ההקשר כחלונית צדדית.

‎"DEVELOPER_TOOLS" הערך הזה מציין שסוג ההקשר הוא 'כלים למפתחים'.

ExtensionContext

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

הקשר שמארח את תוכן התוסף.

מאפיינים

  • contextId

    מחרוזת

    מזהה ייחודי להקשר הזה

  • contextType

    ContextType

    סוג ההקשר שאליו הנתון הזה תואם.

  • documentId

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

    מזהה UUID של המסמך שמשויך להקשר הזה, או לא מוגדר אם ההקשר הזה לא מתארח במסמך.

  • documentOrigin

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

    המקור של המסמך שמשויך להקשר הזה, או לא מוגדר אם ההקשר לא מתארח במסמך.

  • documentUrl

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

    כתובת ה-URL של המסמך שמשויך להקשר הזה, או לא מוגדרת אם ההקשר לא מתארח במסמך.

  • frameId

    number

    המזהה של המסגרת של ההקשר הזה, או -1 אם ההקשר הזה לא מתארח במסגרת.

  • מצב פרטי

    בוליאני

    אם ההקשר משויך לפרופיל פרטי.

  • tabId

    number

    המזהה של הכרטיסייה של ההקשר הזה, או -1 אם ההקשר הזה לא מתארח בכרטיסייה.

  • windowId

    number

    המזהה של החלון של ההקשר הזה, או -1 אם ההקשר הזה לא מתארח בחלון.

MessageSender

אובייקט שמכיל מידע על הקשר הסקריפט ששלח הודעה או בקשה.

מאפיינים

  • documentId

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

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

    מזהה UUID של המסמך שדרכו נפתח החיבור.

  • documentLifecycle

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

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

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

  • frameId

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

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

  • id [מזהה]

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

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

  • nativeApplication

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

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

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

  • מקור

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

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

    המקור של הדף או המסגרת שדרכם נפתח החיבור. היא יכולה להיות שונה מנכס כתובת ה-URL (למשל, about:blank) או יכולה להיות אטומה (למשל, iframes ב-sandbox). המידע הזה שימושי לזיהוי אם המקור מהימן, אם אנחנו לא יכולים לדעת זאת באופן מיידי מכתובת ה-URL.

  • כרטיסייה

    Tab אופציונלי

    ה-tabs.Tab שפתח את החיבור, אם קיים. המאפיין הזה יופיע רק כשהחיבור נפתח מכרטיסייה (כולל סקריפטים של תוכן), ורק אם המכשיר המקבל הוא תוסף ולא אפליקציה.

  • tlsChannelId

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

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

  • כתובת אתר

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

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

OnInstalledReason

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

הסיבה לשליחת האירוע.

Enum

‎"install"
הסיבה לאירוע היא התקנה.

"update"
מציין את הסיבה לאירוע כעדכון של התוסף.

‎"chrome_update"
הסיבה לאירוע היא עדכון של Chrome.

"shared_module_update"
הסיבה לאירוע היא עדכון של מודול משותף.

OnRestartRequiredReason

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

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

Enum

"app_update"
הסיבה לאירוע היא עדכון לאפליקציה.

"os_update"
הסיבה לאירוע היא עדכון למערכת ההפעלה.

"periodic"
הסיבה לאירוע היא הפעלה מחדש תקופתית של האפליקציה.

PlatformArch

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

ארכיטקטורת המעבד של המכונה.

Enum

‎"arm"
מציין את ארכיטקטורת המעבד כ-arm.

‎"arm64"
מציינת את ארכיטקטורת המעבד כ-arm64.

‎"x86-32"
מציין את ארכיטקטורת המעבד כ-x86-32.

‎"x86-64"
מציין את ארכיטקטורת המעבד כ-x86-64.

"mips"
הערך הזה מציין את ארכיטקטורת המעבד כ-mips.

"mips64"
מציין את ארכיטקטורת המעבד כ-mips64.

PlatformInfo

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

מאפיינים

  • קשת

    PlatformArch

    ארכיטקטורת המעבד של המכונה.

  • nacl_arch

    PlatformNaclArch

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

  • מערכת ההפעלה שבה פועל Chrome.

PlatformNaclArch

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

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

Enum

‎"arm"
מציין את ארכיטקטורת הלקוח המקורית כ-arm.

‎"x86-32"
מציין את הארכיטקטורה של הלקוח המקורי כ-x86-32.

"x86-64"
הגדרת הארכיטקטורה של הלקוח המקורי כ-x86-64.

‎"mips"
מציין את ארכיטקטורת הלקוח המקורית כ-mips.

‎"mips64"
מציין את ארכיטקטורת הלקוח המקורית בתור mips64.

PlatformOs

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

מערכת ההפעלה שבה פועל Chrome.

Enum

‎"mac"
מציינת את מערכת ההפעלה macOS.

"win"
מציינת את מערכת ההפעלה Windows.

‎"android"
מציינת את מערכת ההפעלה Android.

'cros'
מציינת את מערכת ההפעלה של Chrome.

‎"linux"
מציינת את מערכת ההפעלה Linux.

‎"openbsd"
מציינת את מערכת ההפעלה OpenBSD.

‎"fuchsia"
מציין את מערכת ההפעלה Fuchsia.

Port

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

מאפיינים

  • שם

    מחרוזת

    שם השקע, כפי שצוין בקריאה ל-runtime.connect.

  • onDisconnect

    Event<functionvoidvoid>

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

    הפונקציה onDisconnect.addListener נראית כך: 

    (callback: function) => {...}

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

      פונקציה

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

      (port: Port) => void

  • onMessage

    Event<functionvoidvoid>

    האירוע הזה מופעל כשהצד השני של היציאה קורא לפונקציה postMessage.

    הפונקציה onMessage.addListener נראית כך: 

    (callback: function) => {...}

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

      פונקציה

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

      (message: any, port: Port) => void

  • שולח

    MessageSender אופציונלי

    המאפיין הזה יופיע רק ביציאות שמועברות למאזינים של onConnect‏ / onConnectExternal‏ / onConnectNative.

  • ניתוק

    void

    צריך לנתק את היציאה באופן מיידי. קריאה ל-disconnect() ביציאה שכבר מנותקת לא משפיעה עליה. כשיציאה מנותקת, לא יישלחו אליה אירועים חדשים.

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

    () => {...}

  • postMessage

    void

    שולחים הודעה לקצה השני של היציאה. אם השקע מנותק, תופיע שגיאה.

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

    (message: any) => {...}

    • הודעה

      כל

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

      ההודעה שרוצים לשלוח. האובייקט הזה צריך להיות ניתן להמרה ל-JSON.

RequestUpdateCheckStatus

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

התוצאה של בדיקת העדכון.

Enum

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

"no_update"
מציין שאין עדכונים זמינים להתקנה.

update_available
מציין שיש עדכון זמין להתקנה.

מאפיינים

id

המזהה של התוסף או האפליקציה.

סוג

מחרוזת

lastError

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

סוג

אובייקט

מאפיינים

  • הודעה

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

    פרטים על השגיאה שהתרחשה.

Methods

connect()

chrome.runtime.connect(
  extensionId?: string,
  connectInfo?: object,
)

ניסיונות לחבר מאזינים בתוך תוסף (כמו דף הרקע) או תוספים/אפליקציות אחרים. האפשרות הזו שימושית לסקריפטים של תוכן שמתחברים לתהליכים של התוספים, לתקשורת בין אפליקציות או תוספים ולהודעות באינטרנט. חשוב לזכור שהקוד הזה לא מתחבר למאזינים בסקריפט תוכן. תוספים יכולים להתחבר לסקריפטים של תוכן שמוטמעים בכרטיסיות באמצעות tabs.connect.

פרמטרים

  • extensionId

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

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

  • connectInfo

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

    • includeTlsChannelId

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

      האם מזהה ערוץ ה-TLS יועבר ל-onConnectExternal עבור תהליכים שמאזינים לאירוע החיבור.

    • שם

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

      יועבר ל-onConnect בתהליכים שמקשיבים לאירוע החיבור.

החזרות

  • יציאה שבאמצעותה אפשר לשלוח ולקבל הודעות. האירוע onDisconnect של השקע יופעל אם התוסף לא קיים.

connectNative()

chrome.runtime.connectNative(
  application: string,
)

חיבור לאפליקציה מקורית במכונה המארחת. בשביל השיטה הזו נדרשת ההרשאה "nativeMessaging". מידע נוסף זמין במאמר הודעות מקוריות.

פרמטרים

  • יישום

    מחרוזת

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

החזרות

  • יציאה שבאמצעותה אפשר לשלוח ולקבל הודעות באמצעות האפליקציה

getBackgroundPage()

Promise חזית בלבד 
chrome.runtime.getBackgroundPage(
  callback?: function,
)

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

פרמטרים

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

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

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

    (backgroundPage?: Window) => void

    • backgroundPage

      חלון אופציונלי

      אובייקט 'window' ב-JavaScript לדף הרקע.

החזרות

  • Promise<Window | undefined>

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

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

getContexts()

Promise Chrome מגרסה 116 ואילך MV3 ואילך 
chrome.runtime.getContexts(
  filter: ContextFilter,
  callback?: function,
)

אחזור מידע על הקשרים הפעילים שמשויכים לתוסף הזה

פרמטרים

  • סינון

    ContextFilter

    מסנן לאיתור הקשרים תואמים. הקשר תואם אם הוא תואם לכל השדות שצוינו במסנן. כל שדה לא מוגדר במסנן תואם לכל ההקשרים.

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

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

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

    (contexts: ExtensionContext[]) => void

    • הקשרים

      ExtensionContext[]

      ההקשרים התואמים, אם יש כאלה.

החזרות

  • Promise<ExtensionContext[]>

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

getManifest()

chrome.runtime.getManifest()

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

החזרות

  • אובייקט

    פרטי המניפסט.

getPackageDirectoryEntry()

Promise חזית בלבד 
chrome.runtime.getPackageDirectoryEntry(
  callback?: function,
)

הפונקציה מחזירה DirectoryEntry לספריית החבילה.

פרמטרים

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

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

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

    (directoryEntry: DirectoryEntry) => void

    • directoryEntry

      DirectoryEntry

החזרות

  • Promise<DirectoryEntry>

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

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

getPlatformInfo()

Promise 
chrome.runtime.getPlatformInfo(
  callback?: function,
)

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

פרמטרים

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

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

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

    (platformInfo: PlatformInfo) => void

החזרות

  • Promise<PlatformInfo>

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

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

getURL()

chrome.runtime.getURL(
  path: string,
)

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

פרמטרים

  • נתיב

    מחרוזת

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

החזרות

  • מחרוזת

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

openOptionsPage()

Promise 
chrome.runtime.openOptionsPage(
  callback?: function,
)

אם אפשר, פותחים את דף האפשרויות של התוסף.

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

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

פרמטרים

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

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

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

    () => void

החזרות

  • Promise<void>

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

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

reload()

chrome.runtime.reload()

טעינת מחדש של האפליקציה או התוסף. השיטה הזו לא נתמכת במצב קיוסק. במצב קיוסק, משתמשים ב-method‏ chrome.runtime.restart().

requestUpdateCheck()

Promise 
chrome.runtime.requestUpdateCheck(
  callback?: function,
)

הבקשה היא לבצע בדיקה מיידית של עדכון לאפליקציה או לתוסף.

חשוב: רוב התוספים או האפליקציות לא צריכים להשתמש בשיטה הזו, כי Chrome כבר מבצע בדיקות אוטומטיות כל כמה שעות, ואפשר להאזין לאירוע runtime.onUpdateAvailable בלי להפעיל את requestUpdateCheck.

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

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

פרמטרים

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

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

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

    (result: object) => void

    • תוצאה

      אובייקט

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

      אובייקט RequestUpdateCheckResult שמכיל את סטטוס בדיקת העדכון ואת כל פרטי התוצאה, אם יש עדכון זמין

      • התוצאה של בדיקת העדכון.

      • גרסה

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

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

החזרות

  • Promise<object>

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

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

restart()

chrome.runtime.restart()

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

restartAfterDelay()

Promise Chrome מגרסה 53 ואילך 
chrome.runtime.restartAfterDelay(
  seconds: number,
  callback?: function,
)

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

פרמטרים

  • שניות

    number

    משך ההמתנה בשניות לפני הפעלת המכשיר מחדש, או -1 כדי לבטל הפעלה מחדש מתוזמנת.

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

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

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

    () => void

החזרות

  • Promise<void>

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

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

sendMessage()

Promise 
chrome.runtime.sendMessage(
  extensionId?: string,
  message: any,
  options?: object,
  callback?: function,
)

שליחת הודעה אחת למאזינים לאירועים בתוך התוסף או בתוסף/באפליקציה אחרים. הדומה ל-runtime.connect, אבל שולחת רק הודעה אחת עם תשובה אופציונלית. אם השליחה היא לתוסף שלכם, האירוע runtime.onMessage יופעל בכל פריים של התוסף (למעט הפריים של השולח), או runtime.onMessageExternal אם מדובר בתוסף אחר. חשוב לזכור שתוספים לא יכולים לשלוח הודעות לסקריפטים של תוכן באמצעות השיטה הזו. כדי לשלוח הודעות לסקריפטים של תוכן, משתמשים ב-tabs.sendMessage.

פרמטרים

  • extensionId

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

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

  • הודעה

    כל

    ההודעה שרוצים לשלוח. ההודעה הזו צריכה להיות אובייקט שניתן להמיר ל-JSON.

  • אפשרויות

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

    • includeTlsChannelId

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

      האם מזהה ערוץ ה-TLS יועבר ל-onMessageExternal עבור תהליכים שמאזינים לאירוע החיבור.

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

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

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

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

    (response: any) => void

    • תשובה

      כל

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

החזרות

  • Promise<any>

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

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

sendNativeMessage()

Promise 
chrome.runtime.sendNativeMessage(
  application: string,
  message: object,
  callback?: function,
)

שליחת הודעה אחת לאפליקציה מקורית. בשביל השיטה הזו נדרשת ההרשאה "nativeMessaging".

פרמטרים

  • יישום

    מחרוזת

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

  • הודעה

    אובייקט

    ההודעה שתישלח למארח להעברת הודעות נייטיב.

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

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

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

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

    (response: any) => void

    • תשובה

      כל

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

החזרות

  • Promise<any>

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

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

setUninstallURL()

Promise 
chrome.runtime.setUninstallURL(
  url: string,
  callback?: function,
)

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

פרמטרים

  • כתובת אתר

    מחרוזת

    כתובת ה-URL שתיפתח אחרי הסרת התוסף. כתובת ה-URL הזו חייבת לכלול את הסכימות http: ‎ או https: ‎. מגדירים מחרוזת ריקה כדי שלא תיפתח כרטיסייה חדשה לאחר ההסרה.

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

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

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

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

    () => void

החזרות

  • Promise<void>

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

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

אירועים

onBrowserUpdateAvailable

הוצא משימוש
chrome.runtime.onBrowserUpdateAvailable.addListener(
  callback: function,
)

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

האירוע מופעל כשיש עדכון ל-Chrome, אבל הוא לא מותקן באופן מיידי כי נדרשת הפעלה מחדש של הדפדפן.

פרמטרים

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

    פונקציה

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

    () => void

onConnect

chrome.runtime.onConnect.addListener(
  callback: function,
)

הפונקציה מופעלת כשמתבצע חיבור מתהליך של תוסף או מסקריפט תוכן (על ידי runtime.connect).

פרמטרים

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

    פונקציה

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

    (port: Port) => void

onConnectExternal

chrome.runtime.onConnectExternal.addListener(
  callback: function,
)

האירוע מופעל כשמתבצע חיבור מתוסף אחר (על ידי runtime.connect) או מאתר אינטרנט שניתן להתחבר אליו באופן חיצוני.

פרמטרים

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

    פונקציה

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

    (port: Port) => void

onConnectNative

Chrome מגרסה 76 ואילך 
chrome.runtime.onConnectNative.addListener(
  callback: function,
)

האירוע מופעל כשמתבצע חיבור מאפליקציה מקורית. כדי לבצע את האירוע הזה נדרשת ההרשאה "nativeMessaging". התכונה נתמכת רק ב-Chrome OS.

פרמטרים

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

    פונקציה

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

    (port: Port) => void

onInstalled

chrome.runtime.onInstalled.addListener(
  callback: function,
)

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

פרמטרים

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

    פונקציה

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

    (details: object) => void

    • פרטים

      אובייקט

      • id [מזהה]

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

        המזהה של תוסף המודול המשותף שיובא ועודכן. השדה הזה מופיע רק אם הערך של 'reason' הוא 'shared_module_update'.

      • previousVersion

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

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

      • הסיבה לשליחת האירוע.

onMessage

chrome.runtime.onMessage.addListener(
  callback: function,
)

האירוע מופעל כשהודעה נשלחת מתהליך של תוסף (על ידי runtime.sendMessage) או מסקריפט תוכן (על ידי tabs.sendMessage).

פרמטרים

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

    פונקציה

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

    (message: any, sender: MessageSender, sendResponse: function) => boolean | undefined

    • הודעה

      כל

    • שולח

      MessageSender

    • sendResponse

      פונקציה

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

      () => void

    • החזרות

      boolean | undefined

onMessageExternal

chrome.runtime.onMessageExternal.addListener(
  callback: function,
)

האירוע מופעל כשהודעה נשלחת מתוסף אחר (על ידי runtime.sendMessage). אי אפשר להשתמש בו בסקריפט תוכן.

פרמטרים

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

    פונקציה

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

    (message: any, sender: MessageSender, sendResponse: function) => boolean | undefined

    • הודעה

      כל

    • שולח

      MessageSender

    • sendResponse

      פונקציה

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

      () => void

    • החזרות

      boolean | undefined

onRestartRequired

chrome.runtime.onRestartRequired.addListener(
  callback: function,
)

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

פרמטרים

onStartup

chrome.runtime.onStartup.addListener(
  callback: function,
)

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

פרמטרים

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

    פונקציה

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

    () => void

onSuspend

chrome.runtime.onSuspend.addListener(
  callback: function,
)

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

פרמטרים

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

    פונקציה

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

    () => void

onSuspendCanceled

chrome.runtime.onSuspendCanceled.addListener(
  callback: function,
)

נשלח אחרי onSuspend כדי לציין שהאפליקציה לא תוריד אחרי הכל.

פרמטרים

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

    פונקציה

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

    () => void

onUpdateAvailable

chrome.runtime.onUpdateAvailable.addListener(
  callback: function,
)

האירוע מופעל כשיש עדכון זמין, אבל הוא לא מותקן באופן מיידי כי האפליקציה פועלת כרגע. אם לא תעשו כלום, העדכון יותקן בפעם הבאה שדף הרקע פורק. אם אתם רוצים שהעדכון יותקן מוקדם יותר, תוכלו לבצע קריאה מפורשת ל-chrome.runtime.reload(). אם התוסף שלכם משתמש בדף רקע מתמיד, דף הרקע אף פעם לא פורק, לכן אם לא תבצעו קריאה ידנית ל-chrome.runtime.reload() בתגובה לאירוע הזה, העדכון לא יותקן עד להפעלה מחדש הבאה של Chrome עצמו. אם אין בוררים שמקשיבים לאירוע הזה, ולתוסף יש דף רקע מתמיד, הוא יפעל כאילו מתבצעת קריאה ל-chrome.runtime.reload() בתגובה לאירוע הזה.

פרמטרים

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

    פונקציה

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

    (details: object) => void

    • פרטים

      אובייקט

      • גרסה

        מחרוזת

        מספר הגרסה של העדכון הזמין.

onUserScriptConnect

גרסה 115 ואילך של Chrome גרסה MV3 ואילך של MV3 
chrome.runtime.onUserScriptConnect.addListener(
  callback: function,
)

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

פרמטרים

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

    פונקציה

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

    (port: Port) => void

onUserScriptMessage

גרסה 115 ואילך של Chrome גרסה MV3 ואילך של MV3 
chrome.runtime.onUserScriptMessage.addListener(
  callback: function,
)

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

פרמטרים

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

    פונקציה

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

    (message: any, sender: MessageSender, sendResponse: function) => boolean | undefined

    • הודעה

      כל

    • שולח

      MessageSender

    • sendResponse

      פונקציה

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

      () => void

    • החזרות

      boolean | undefined