chrome.runtime

תיאור

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

סקירה כללית

Runtime API מספק שיטות לתמיכה בכמה תחומי פונקציונליות שהתוספים יכולים להשתמש:

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

הרשאות

רוב השיטות ב-Runtime API לא מחייבות הרשאה כלשהי, מלבד sendNativeMessage ו-connectNative, נדרשת ההרשאה nativeMessaging.

מניפסט

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

manifest.json:

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

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

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

כדי שדף אינטרנט יוכל לגשת לנכס שמתארח בדומיין אחר, צריך לציין את כתובת ה-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);
});

background.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');
  }
});

דוגמאות לתוספים

דוגמאות נוספות של Runtime API מופיעות בהדגמה של המניפסט V3 – Web Accessible Resources.

סוגים

ContextFilter

Chrome 114 ואילך

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

מאפיינים

  • contextIds

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

  • contextTypes

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

  • documentIds

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

  • documentOrigins

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

  • documentUrls

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

  • frameIds

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

  • גלישה פרטית

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

  • tabIds

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

  • windowIds

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

ContextType

Chrome 114 ואילך

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

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

    Chrome 106+

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

  • documentLifecycle

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

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

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

  • frameId

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

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

  • id [מזהה]

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

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

  • nativeApplication

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

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

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

  • מקור

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

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

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

  • כרטיסייה

    Tab אופציונלי

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

  • tlsChannelId

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

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

  • כתובת אתר

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

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

OnInstalledReason

Chrome 44 ואילך

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

Enum

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

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

&quot;chrome_update&quot;
מציין את סיבת האירוע בתור עדכון של Chrome.

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

OnRestartRequiredReason

Chrome 44 ואילך

הסיבה לשליחת האירוע. '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

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

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

PlatformNaclArch

Chrome 44 ואילך

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

Enum

"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 עשוי להיכלל אם היציאה התנתקה בגלל שגיאה. אם השקע נסגר דרך ניתוק, האירוע הזה יופעל רק בצד השני. האירוע הזה מופעל לכל היותר פעם אחת (ראו גם משך החיים של יציאה).

    הפונקציה 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.

  • ניתוק

    ריק

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

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

    () => {...}

  • postMessage

    void

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

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

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

    • הודעה

      כל

      Chrome 52 ואילך

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

RequestUpdateCheckStatus

Chrome 44 ואילך

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

Enum

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

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

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

מאפיינים

id

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

סוג

מחרוזת

lastError

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

סוג

אובייקט

מאפיינים

  • הודעה

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

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

שיטות

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()

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

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

פרמטרים

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

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

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

    (backgroundPage?: Window) => void

    • backgroundPage

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

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

החזרות

  • Promise<Window | undefined>

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

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

getContexts()

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

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

פרמטרים

  • סינון

    ContextFilter

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

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

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

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

    (contexts: ExtensionContext[]) => void

    • ההקשרים

      ExtensionContext[]

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

החזרות

  • Promise&lt;ExtensionContext[]&gt;

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

getManifest()

chrome.runtime.getManifest()

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

החזרות

  • אובייקט

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

getPackageDirectoryEntry()

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

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

פרמטרים

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

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

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

    (directoryEntry: DirectoryEntry) => void

    • directoryEntry

      DirectoryEntry

החזרות

  • Promise<DirectoryEntry>

    Chrome 122 ואילך

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

getPlatformInfo()

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

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

פרמטרים

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

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

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

    (platformInfo: PlatformInfo) => void

החזרות

  • Promise<PlatformInfo>

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

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

getURL()

chrome.runtime.getURL(
  path: string,
)

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

פרמטרים

  • נתיב

    מחרוזת

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

החזרות

  • מחרוזת

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

openOptionsPage()

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

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

ההתנהגות המדויקת עשויה להשתנות בהתאם למפתח [options_ui](https://developer.chrome.com/docs/extensions/develop/ui/options-page#embedded_options) או [options_page](https://developer.chrome.com/docs/extensions/develop/ui/options-page#full_page) של המניפסט, או בהתאם ליכולות של Chrome באותו זמן. לדוגמה, הדף עשוי להיפתח בכרטיסייה חדשה, בכתובת chrome://extensions, באפליקציה או פשוט להתמקד בדף האפשרויות הפתוח. הוא אף פעם לא יגרום לטעינה מחדש של הדף של מבצע הקריאה החוזרת.

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

פרמטרים

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

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

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

    () => void

החזרות

  • הבטחה<Empty>

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

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

reload()

chrome.runtime.reload()

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

requestUpdateCheck()

הבטחה 
chrome.runtime.requestUpdateCheck(
  callback?: function,
)

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

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

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

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

פרמטרים

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

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

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

    (result: object) => void

    • תוצאה

      אובייקט

      Chrome 109+

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

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

      • גרסה

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

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

החזרות

  • Promise<object>

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

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

restart()

chrome.runtime.restart()

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

restartAfterDelay()

הבטחה Chrome 53 ואילך 
chrome.runtime.restartAfterDelay(
  seconds: number,
  callback?: function,
)

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

פרמטרים

  • שניות

    number

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

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

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

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

    () => void

החזרות

  • הבטחה<Empty>

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

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

sendMessage()

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

החזרות

  • הבטחה<כלשהו>

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

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

sendNativeMessage()

הבטחה 
chrome.runtime.sendNativeMessage(
  application: string,
  message: object,
  callback?: function,
)

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

פרמטרים

  • יישום

    מחרוזת

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

  • הודעה

    אובייקט

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

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

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

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

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

    (response: any) => void

    • תשובה

      כל

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

החזרות

  • הבטחה<כלשהו>

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

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

setUninstallURL()

הבטחה 
chrome.runtime.setUninstallURL(
  url: string,
  callback?: function,
)

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

פרמטרים

  • כתובת אתר

    מחרוזת

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

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

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

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

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

    () => void

החזרות

  • הבטחה<Empty>

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

    הבטחות נתמכות רק במניפסט מגרסה V3 ואילך, בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (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.

פרמטרים

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

    פונקציה

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

    (port: Port) => void

onInstalled

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

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

פרמטרים

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

    פונקציה

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

    (details: object) => void

    • פרטים

      אובייקט

      • id [מזהה]

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

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

      • previousVersion

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

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

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

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 | לא מוגדר

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

Chrome 115+ MV3+ 
chrome.runtime.onUserScriptConnect.addListener(
  callback: function,
)

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

פרמטרים

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

    פונקציה

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

    (port: Port) => void

onUserScriptMessage

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

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

פרמטרים

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

    פונקציה

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

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

    • הודעה

      כל

    • שולח

      MessageSender

    • sendResponse

      פונקציה

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

      () => void

    • החזרות

      boolean | undefined