דף זה תורגם על ידי 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"
  ],
  ...
}

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

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

העברת הודעות: התוסף יכול לתקשר עם הקשרים שונים בתוסף וגם עם תוספים אחרים באמצעות השיטות והאירועים הבאים: connect(), onConnect, onConnectExternal, sendMessage(), onMessage ו- onMessageExternal. בנוסף, התוסף יכול להעביר הודעות לאפליקציות מקומיות במכשיר של המשתמש באמצעות connectNative() ו- sendNativeMessage().

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

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

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

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

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

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

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

manifest.json:

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

content.js:

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

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

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

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

content.js:

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

‫service-worker.js:

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

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

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

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

background.js:

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

דוגמאות

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

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

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

החזרות

‫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 המלאה של המשאב.

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

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 [מזהה]
    
    מחרוזת אופציונלי
    
    מציין את המזהה של התוסף המיובא של המודול המשותף שעודכן. השדה הזה מופיע רק אם הערך של '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 | 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
```
- 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 נראה כך:
```
() => 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()

פרמטרים

החזרות

openOptionsPage()

החזרות

reload()

requestUpdateCheck()

החזרות

restart()

restartAfterDelay()

פרמטרים

החזרות

sendMessage()

פרמטרים

החזרות

sendNativeMessage()

פרמטרים

החזרות

setUninstallURL()

פרמטרים

החזרות

אירועים

chrome.runtime