‫Chrome תומך עכשיו במרחב השמות browser.* שעבר סטנדרטיזציה (זמין מגרסה 148 של Chrome). אנחנו מעדכנים את התיעוד בהדרגה. מידע נוסף זמין במדריך המעבר.

‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

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

התנהגות של תוסף מסוג unpacked

כשטוענים מחדש תוסף לא ארוז, הפעולה הזו נחשבת לעדכון. כלומר, האירוע 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');
  }
});

דוגמאות

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

סוגים

ContextFilter

‫Chrome 114 ואילך

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

מאפיינים

contextIds

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

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

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

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

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

‫number[] אופציונלי
מצב פרטי

‫boolean אופציונלי
tabIds

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

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

ContextType

‫Chrome 114 ואילך

ספירה

‫"TAB"
מציין את סוג ההקשר ככרטיסייה

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

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

‫"OFFSCREEN_DOCUMENT"
מציין את סוג ההקשר כמסמך מחוץ למסך.

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

‫"DEVELOPER_TOOLS"
מציין את סוג ההקשר ככלים למפתחים.

ExtensionContext

‫Chrome 114 ואילך

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

מאפיינים

contextId

מחרוזת

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

ContextType

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

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

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

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

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

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

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

number

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

בוליאני

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

number

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

number

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

MessageSender

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

מאפיינים

documentId

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

‫Chrome 106 ואילך

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

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

‫Chrome 106 ואילך

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

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

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

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

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

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

‫Chrome 74 ואילך

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

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

‫Chrome 80 ואילך

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

‫Tab אופציונלי

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

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

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

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

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

OnInstalledReason

‫Chrome 44 ואילך

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

ספירה

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

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

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

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

OnRestartRequiredReason

‫Chrome 44 ואילך

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

ספירה

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

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

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

PlatformArch

‫Chrome 44 ואילך

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

ספירה

‫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.
ארכיטקטורת הלקוח המותאם. יכול להיות שהשם יהיה שונה בפלטפורמות מסוימות.
os

PlatformOs

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

PlatformNaclArch

‫Chrome 44 ואילך הוצא משימוש מאז Chrome 149

הספירה הזו הוצאה משימוש אחרי ההסרה המלאה של Native Client.

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

ספירה

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

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

‫"x86-64"
מציין את ארכיטקטורת הלקוח המקורי כ-x86-64.

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

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

PlatformOs

‫Chrome 44 ואילך

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

ספירה

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

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

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

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

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

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

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.
ניתוק

void

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

הפונקציה disconnect נראית כך:
```
() => {...}
```
postMessage

void

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

הפונקציה postMessage נראית כך:
```
(message: any) => {...}
```
- הודעה
  
  כל
  
  ‫Chrome 52 ואילך
  
  ההודעה לשליחה. האובייקט הזה צריך להיות ניתן להמרה ל-JSON.

RequestUpdateCheckStatus

‫Chrome 44 ואילך

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

ספירה

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

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

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

מאפיינים

id

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

סוג

מחרוזת

lastError

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

סוג

אובייקט

מאפיינים

הודעה

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

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

Methods

connect()

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

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

פרמטרים

extensionId

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

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

אובייקט אופציונלי
- includeTlsChannelId
  
  ‫boolean אופציונלי
  
  האם מזהה ערוץ ה-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()

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

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

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

החזרות

Promise<void>

‫Chrome 99 ואילך

reload()

chrome.runtime.reload(): void

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

requestUpdateCheck()

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

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

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

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

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

החזרות

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>

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

פרמטרים

extensionId

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

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

כל

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

אובייקט אופציונלי
- includeTlsChannelId
  
  ‫boolean אופציונלי
  
  האם מזהה הערוץ של TLS יועבר אל onMessageExternal לתהליכים שממתינים לאירוע החיבור.

החזרות

Promise<any>

‫Chrome 99 ואילך

נוספה תמיכה ב-Promise בהקשרים של תוספים ב-Chrome 99. כשמתקשרים מדף אינטרנט לתוסף, אפשר להשתמש ב-Promises מגרסה 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.runtime.onEnabled.addListener(
  callback: function,
)

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

פרמטרים

callback

פונקציה

הפרמטר callback נראה כך:
```
() => void
```

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
```
  - תשובה
    
    כל אופציונלי
    
    התשובה שמוחזרת לשולח ההודעה.
- החזרות
  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
```
  - תשובה
    
    כל אופציונלי
    
    התשובה שמוחזרת לשולח ההודעה.
- החזרות
  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
```
  - תשובה
    
    כל אופציונלי
    
    התשובה שמוחזרת לשולח ההודעה.
- החזרות
  ‫boolean | undefined

chrome.runtime קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.

תיאור

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

התנהגות של תוסף מסוג unpacked

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

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

שליחת נתונים מסקריפט תוכן אל Service Worker

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

דוגמאות

סוגים

ContextFilter

מאפיינים

ContextType

ספירה

ExtensionContext

מאפיינים

MessageSender

מאפיינים

OnInstalledReason

ספירה

OnRestartRequiredReason

ספירה

PlatformArch

ספירה

PlatformInfo

מאפיינים

PlatformNaclArch

ספירה

PlatformOs

ספירה

Port

מאפיינים

RequestUpdateCheckStatus

ספירה

מאפיינים

id

סוג

lastError

סוג

מאפיינים

Methods

connect()

פרמטרים

החזרות

connectNative()

פרמטרים

החזרות

getBackgroundPage()

החזרות

getContexts()

פרמטרים

החזרות

getManifest()

החזרות

getPackageDirectoryEntry()

החזרות

getPlatformInfo()

החזרות

getURL()

פרמטרים

החזרות

getVersion()

החזרות

openOptionsPage()

החזרות

reload()

requestUpdateCheck()

החזרות

restart()

restartAfterDelay()

פרמטרים

החזרות

sendMessage()

פרמטרים

החזרות

sendNativeMessage()

פרמטרים

החזרות

setUninstallURL()

פרמטרים

chrome.runtime