browser.runtime

תיאור

משתמשים ב-API של chrome.runtime כדי לאחזר את ה-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()`.

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

כשטוענים מחדש תוסף לא ארוז, הפעולה נחשבת לעדכון. כלומר, האירוע browser.runtime.onInstalled יופעל עם הסיבה "update". זה כולל מקרים שבהם התוסף נטען מחדש באמצעות browser.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 = browser.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
browser.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'
};

browser.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:

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

דוגמאות

בהדגמה של Manifest V3 – משאבים נגישים באינטרנט יש דוגמאות נוספות ל-Runtime API.

סוגים

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

‫Chrome מגרסה 114 ואילך

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

מאפיינים

• contextId

  מחרוזת

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

• contextType

  ContextType

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

• documentId

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

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

• documentOrigin

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

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

• documentUrl

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

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

• frameId

  number

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

• גלישה בסתר

  בוליאני

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

• tabId

  number

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

• windowId

  number

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

ExtensionLoadDetails

‫Chrome מגרסה 157 ואילך

פרטים על אירוע הטעינה של התוסף.

מאפיינים

• previousVersion

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

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

• reason

  OnLoadedReason

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

MessageSender

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

מאפיינים

• documentId

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

  ‫Chrome מגרסה 106 ואילך

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

• documentLifecycle

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

  ‫Chrome מגרסה 106 ואילך

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

• frameId

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

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

• id [מזהה]

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

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

• nativeApplication

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

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

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

• origin

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

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

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

• Tab

  כרטיסייה אופציונלי

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

• tlsChannelId

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

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

• url

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

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

OnInstalledReason

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

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

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

‫"install"
מציין שהסיבה לאירוע היא התקנה.

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

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

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

OnLoadedReason

‫Chrome מגרסה 157 ואילך

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

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

"install"
התוסף הותקן לאחרונה.

"update"
התוסף נטען מחדש אחרי עדכון.

‫"browser_update"
הדפדפן עודכן לגרסה חדשה.

"enable"
התוסף הופעל מחדש אחרי שהיה מושבת.

"startup"
התוסף נטען במהלך הפעלת הדפדפן.

"reload"
התוסף נטען מחדש (למשל, באמצעות chrome.runtime.reload()‎ או שהמשתמש טען מחדש את התוסף באופן ידני).

OnRestartRequiredReason

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

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

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

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

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

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

PlatformArch

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

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

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

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

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

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

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

"mips"
מגדיר את ארכיטקטורת המעבד כ-mips.

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

"riscv64"
מגדיר את ארכיטקטורת המעבד כ-riscv64.

PlatformInfo

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

מאפיינים

• קשת

  PlatformArch

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

• nacl_arch

  PlatformNaclArch אופציונלי

  הוצאה משימוש החל מגרסת Chrome 149

  המאפיין הזה הוצא משימוש בעקבות הסרה מלאה של Native Client.

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

• os

  PlatformOs

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

PlatformNaclArch

‫Chrome מגרסה 44 ואילך הוצא משימוש החל מגרסה 149 של Chrome

הערך הזה הוצא משימוש בעקבות הסרה מלאה של Native Client.

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

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

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

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

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

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

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

PlatformOs

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

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

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

"mac"
מציין את מערכת ההפעלה MacOS.

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

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

"cros"
מציין את מערכת ההפעלה של Chrome.

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

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

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

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

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

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

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

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

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

מאפיינים

id

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

סוג

מחרוזת

lastError

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

סוג

אובייקט

מאפיינים

• הודעה

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

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

Methods

connect()

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

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

פרמטרים

• extensionId

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

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

• connectInfo

  object optional

  • includeTlsChannelId

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

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

  • שם

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

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

החזרות

• יציאה

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

connectNative()

chrome.runtime.connectNative(
  application: string,
): Port

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

פרמטרים

• יישום

  מחרוזת

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

החזרות

• יציאה

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

getBackgroundPage()

חזית בלבד הוצא משימוש בגרסה Chrome 133

chrome.runtime.getBackgroundPage(): Promise<Window | undefined>

דפי רקע לא קיימים בתוספי MV3.

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

החזרות

• Promise<Window | undefined>

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

getContexts()

‫Chrome מגרסה 116 ואילך ‫MV3 ואילך

chrome.runtime.getContexts(
  filter: ContextFilter,
): Promise<ExtensionContext[]>

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

פרמטרים

• סינון

  ContextFilter

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

החזרות

• Promise<ExtensionContext[]>

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

getManifest()

chrome.runtime.getManifest(): object

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

החזרות

• אובייקט

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

getPackageDirectoryEntry()

חזית בלבד

chrome.runtime.getPackageDirectoryEntry(): Promise<DirectoryEntry>

מחזירה DirectoryEntry לספריית החבילה.

החזרות

• Promise<DirectoryEntry>

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

getPlatformInfo()

chrome.runtime.getPlatformInfo(): Promise<PlatformInfo>

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

החזרות

• Promise<PlatformInfo>

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

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

getURL()

chrome.runtime.getURL(
  path: string,
): string

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

פרמטרים

• נתיב

  מחרוזת

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

החזרות

• מחרוזת

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

getVersion()

‫Chrome מגרסה 143 ואילך

chrome.runtime.getVersion(): string

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

החזרות

• מחרוזת

  גרסת התוסף.

openOptionsPage()

chrome.runtime.openOptionsPage(): Promise<void>

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

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

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

החזרות

• Promise<void>

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

reload()

chrome.runtime.reload(): void

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

requestUpdateCheck()

chrome.runtime.requestUpdateCheck(): Promise<object>

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

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

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

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

החזרות

• Promise<object>

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

restart()

chrome.runtime.restart(): void

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

restartAfterDelay()

‫Chrome 53 ואילך

chrome.runtime.restartAfterDelay(
  seconds: number,
): Promise<void>

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

פרמטרים

• שניות

  number

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

החזרות

• Promise<void>

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

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

sendMessage()

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

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

פרמטרים

• extensionId

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

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

• הודעה

  כל

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

• אפשרויות

  object optional

  • includeTlsChannelId

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

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

החזרות

• Promise<any>

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

  ב-Chrome 99 נוספה תמיכה ב-Promise להקשרים של תוספים. כשמתקשרים מדף אינטרנט לתוסף, ההבטחות זמינות מ-Chrome 118.

sendNativeMessage()

chrome.runtime.sendNativeMessage(
  application: string,
  message: object,
): Promise<any>

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

פרמטרים

• יישום

  מחרוזת

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

• הודעה

  אובייקט

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

החזרות

• Promise<any>

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

setUninstallURL()

chrome.runtime.setUninstallURL(
  url: string,
): Promise<void>

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

פרמטרים

• url

  מחרוזת

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

החזרות

• Promise<void>

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

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

אירועים

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". היא נתמכת רק ב-ChromeOS.

פרמטרים

• callback

  פונקציה

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

  (port: Port) => void

  • יציאה

    יציאה

onEnabled

‫Chrome מגרסה 155 ואילך

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

מופעל כשתוסף עובר ממצב מושבת למצב מופעל.

פרמטרים

• callback

  פונקציה

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

  () => void

onExtensionLoaded

‫Chrome מגרסה 157 ואילך

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

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

פרמטרים

• callback

  פונקציה

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

  (details: ExtensionLoadDetails) => void

  • פרטים

    ExtensionLoadDetails

onInstalled

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

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

פרמטרים

• callback

  פונקציה

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

  (details: object) => void

  • פרטים

    אובייקט

    • id [מזהה]

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

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

    • previousVersion

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

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

    • reason

      OnInstalledReason

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

onMessage

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

מופעל כשנשלחת הודעה מ-runtime.sendMessage או מ-tabs.sendMessage.

פרמטרים

• callback

  פונקציה

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

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

  • הודעה

    כל

  • שולח

    MessageSender

  • sendResponse

    פונקציה

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

    (response?: any) => void

    • תשובה

      any optional

      התשובה שתוחזר לשולח ההודעה.

  • החזרות

    boolean | Promise<any> | undefined

onMessageExternal

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

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

פרמטרים

• callback

  פונקציה

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

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

  • הודעה

    כל

  • שולח

    MessageSender

  • sendResponse

    פונקציה

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

    (response?: any) => void

    • תשובה

      any optional

      התשובה שתוחזר לשולח ההודעה.

  • החזרות

    boolean | Promise<any> | undefined

onRestartRequired

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

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

פרמטרים

• callback

  פונקציה

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

  (reason: OnRestartRequiredReason) => void

  • reason

    OnRestartRequiredReason

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

‫Chrome 115 ואילך ‫MV3 ואילך

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

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

פרמטרים

• callback

  פונקציה

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

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

  • הודעה

    כל

  • שולח

    MessageSender

  • sendResponse

    פונקציה

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

    (response?: any) => void

    • תשובה

      any optional

      התשובה שתוחזר לשולח ההודעה.

  • החזרות

    boolean | undefined