דף זה תורגם על ידי Cloud Translation API.

chrome.runtime

תיאור

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

רוב הפונקציות ב-API הזה לא דורשות הרשאות. ההרשאה הזו נדרשת ל-connectNative(), ל-sendNativeMessage() ול-onNativeConnect.

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

manifest.json:

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

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

ממשק ה-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');
  }
});

דוגמאות

בהדגמה של משאבים שניתן לגשת אליהם באינטרנט – 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 ואילך

Enum

‫"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) או אטום (למשל, sandboxed iframes). המידע הזה שימושי כדי לזהות אם אפשר לסמוך על המקור, אם אי אפשר לדעת את זה מיד מכתובת ה-URL.
כרטיסייה

Tab אופציונלי

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

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

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

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

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

OnInstalledReason

‫Chrome 44 ואילך

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

Enum

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

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

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

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

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 optional

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

PlatformOs

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

PlatformNaclArch

‫Chrome 44 ואילך

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

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

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

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

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

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

מאפיינים

id

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

סוג

מחרוזת

lastError

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

סוג

אובייקט

מאפיינים

הודעה

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

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

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

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

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.

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

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

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 הזו חייבת לכלול סכימה של http: ‎ או https: ‎. מגדירים מחרוזת ריקה כדי לא לפתוח כרטיסייה חדשה אחרי הסרת ההתקנה.

החזרות

Promise<void>

‫Chrome 99 ואילך

אירועים

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
```
- ניוד
  
  יציאה

onInstalled

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

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

פרמטרים

callback

פונקציה

הפרמטר callback נראה כך:
```
(details: object) => void
```
- פרטים
  
  אובייקט
  - id [מזהה]
    
    מחרוזת אופציונלי
    
    מציין את המזהה של התוסף המיובא של המודול המשותף שעודכן. המאפיין הזה מופיע רק אם הערך של המאפיין 'סיבה' הוא 'shared_module_update'.
  - previousVersion
    
    מחרוזת אופציונלי
    
    מציין את הגרסה הקודמת של התוסף, שזה עתה עודכנה. השדה הזה מופיע רק אם הערך של 'סיבה' הוא 'עדכון'.
  - סיבה
    
    OnInstalledReason
    
    הסיבה לשליחת האירוע.

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 שעות תסתיים. נכון לעכשיו, האירוע הזה מופעל רק באפליקציות למסופים של ChromeOS.

פרמטרים

callback

פונקציה

הפרמטר callback נראה כך:
```
(reason: OnRestartRequiredReason) => void
```
- סיבה
  
  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 נראה כך:
```
() => void
```
- החזרות
  ‫boolean | undefined

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

תיאור

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

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

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

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

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

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

דוגמאות

סוגים

ContextFilter

מאפיינים

ContextType

Enum

ExtensionContext

מאפיינים

MessageSender

מאפיינים

OnInstalledReason

Enum

OnRestartRequiredReason

Enum

PlatformArch

Enum

PlatformInfo

מאפיינים

PlatformNaclArch

Enum

PlatformOs

Enum

Port

מאפיינים

RequestUpdateCheckStatus

Enum

מאפיינים

id

סוג

lastError

סוג

מאפיינים

Methods

connect()

פרמטרים

החזרות

connectNative()

פרמטרים

החזרות

getBackgroundPage()

החזרות

getContexts()

פרמטרים

החזרות

getManifest()

החזרות

getPackageDirectoryEntry()

החזרות

getPlatformInfo()

החזרות

getURL()

פרמטרים

החזרות

getVersion()

החזרות

openOptionsPage()

החזרות

reload()

requestUpdateCheck()

החזרות

restart()

restartAfterDelay()

פרמטרים

החזרות

sendMessage()

פרמטרים

החזרות

sendNativeMessage()

פרמטרים

החזרות

setUninstallURL()

פרמטרים

chrome.runtime