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

chrome.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()'.

התנהגות של תוסף 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 - Web Accessible Resources דוגמאות נוספות ל-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"
מציין את סוג ההקשר כחלונית צדדית.

ExtensionContext

Chrome 114 ומעלה

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

תכונות

contextId

מחרוזת

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

ContextType

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

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

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

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

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

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

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

מספר

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

boolean

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

מספר

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

מספר

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

MessageSender

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

תכונות

documentId

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

Chrome 106 ומעלה

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

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

Chrome 106 ומעלה

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

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

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

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

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

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

Chrome 74 ומעלה

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

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

Chrome 80 ומעלה

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

Tab אופציונלי

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

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

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

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

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

OnInstalledReason

Chrome 44 ואילך

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

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

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

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

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

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

OnRestartRequiredReason

Chrome 44 ואילך

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

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

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

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

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

PlatformArch

Chrome 44 ואילך

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

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

"זרוע"
הגדרה של ארכיטקטורת תהליך לעיבוד כזרוע.

"arm64"
הגדרה של ארכיטקטורת העיבוד (gclouder) כ-Arm64.

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

'x86-64'
ההגדרה של ארכיטקטורת העיבוד (CPU) מוגדרת כ-x86-64.

"mips"
הגדרה של ארכיטקטורת תהליך לעיבוד כ-Mips.

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

PlatformInfo

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

תכונות

קשת

PlatformArch

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

PlatformNaclArch

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

PlatformOs

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

PlatformNaclArch

Chrome 44 ואילך

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

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

"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.

"פוקסיה"
מציין את מערכת ההפעלה של Fuchsia.

Port

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

תכונות

name

מחרוזת

שם השקע, כפי שצוין בשיחה אל runtime.connect.
onDisconnect

אירוע<functionvoidvoid>

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

הפונקציה onDisconnect.addListener נראית כך:
```
(callback: function)=> {...}
```
- קריאה חוזרת (callback)
  
  פונקציה
  
  הפרמטר callback נראה כך:
```
(port: Port)=>void
```
  - יציאה
    
    יציאה
onMessage

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

סוג

אובייקט

תכונות

הודעה

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

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

שיטות

connect()

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

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

פרמטרים

extensionId

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

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

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

החזרות

יציאה

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

connectNative()

chrome.runtime.connectNative(
  application: string,
)

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

פרמטרים

יישום

מחרוזת

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

החזרות

יציאה

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

getBackgroundPage()

הבטחה חזית בלבד

chrome.runtime.getBackgroundPage(
  callback?: function,
)

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

פרמטרים

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

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

הפרמטר callback נראה כך:
```
(backgroundPage?: Window)=>void
```
- backgroundPage
  
  חלון אופציונלי
  
  אובייקט 'חלון' של JavaScript עבור דף הרקע.

החזרות

הבטחה<חלון|לא מוגדר>

Chrome 99 ומעלה

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

getContexts()

Promise Chrome 116+ MV3+

chrome.runtime.getContexts(
  filter: ContextFilter,
  callback?: function,
)

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

פרמטרים

סינון

ContextFilter

מסנן לאיתור הקשרים תואמים. הקשר מסוים תואם אם הוא תואם לכל השדות שצוינו במסנן. כל שדה שלא צוין במסנן תואם לכל ההקשרים.
קריאה חוזרת (callback)

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

הפרמטר callback נראה כך:
```
(contexts: ExtensionContext[])=>void
```
- הקשרים
  
  ExtensionContext[]
  
  ההקשרים התואמים, אם יש.

החזרות

Promise<ExtensionContext[]>

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

getManifest()

chrome.runtime.getManifest()

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

החזרות

אובייקט

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

getPackageDirectoryEntry()

הבטחה חזית בלבד

chrome.runtime.getPackageDirectoryEntry(
  callback?: function,
)

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

פרמטרים

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

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

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

החזרות

Promise<DirectoryEntry>

Chrome 122 ומעלה

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

getPlatformInfo()

הבטחה

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

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

פרמטרים

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

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

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

החזרות

Promise<PlatformInfo>

Chrome 99 ומעלה

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

getURL()

chrome.runtime.getURL(
  path: string,
)

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

פרמטרים

נתיב

מחרוזת

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

החזרות

מחרוזת

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

openOptionsPage()

הבטחה

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

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

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

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

פרמטרים

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

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

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

החזרות

Promise<void>

Chrome 99 ומעלה

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

reload()

chrome.runtime.reload()

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

requestUpdateCheck()

הבטחה

chrome.runtime.requestUpdateCheck(
  callback?: function,
)

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

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

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

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

פרמטרים

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

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

הפרמטר callback נראה כך:
```
(result: object)=>void
```
- תוצאה אחת
  
  אובייקט
  
  Chrome 109 ומעלה
  
  אובייקט RequestUpdateCheck result שבו נשמר הסטטוס של בדיקת העדכונים והפרטים של התוצאה אם יש עדכון זמין
  - status
    
    RequestUpdateCheckStatus
    
    התוצאה של בדיקת העדכונים
  - גרסה
    
    מחרוזת אופציונלי
    
    אם יש עדכון זמין, היא מכילה את הגרסה של העדכון הזמין.

החזרות

Promise<object>

Chrome 109 ומעלה

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

restart()

chrome.runtime.restart()

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

restartAfterDelay()

Promise Chrome 53 ואילך

chrome.runtime.restartAfterDelay(
  seconds: number,
  callback?: function,
)

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

פרמטרים

שניות

מספר

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

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

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

החזרות

Promise<void>

Chrome 99 ומעלה

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

sendMessage()

הבטחה

chrome.runtime.sendMessage(
  extensionId?: string,
  message: any,
  options?: object,
  callback?: function,
)

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

פרמטרים

extensionId

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

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

הכול

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

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

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

Chrome 99 ומעלה

הפרמטר callback נראה כך:
```
(response: any)=>void
```
- תשובה
  
  הכול
  
  אובייקט תגובת JSON שנשלח על ידי ה-handler של ההודעה. אם תתרחש שגיאה במהלך ההתחברות לתוסף, תתבצע קריאה חוזרת ללא ארגומנטים והסמל runtime.lastError יוגדר כהודעת השגיאה.

החזרות

מבטיח<any>

Chrome 99 ומעלה

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

sendNativeMessage()

הבטחה

chrome.runtime.sendNativeMessage(
  application: string,
  message: object,
  callback?: function,
)

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

פרמטרים

יישום

מחרוזת

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

אובייקט

ההודעה שתועבר למארח המקורי של העברת ההודעות.
קריאה חוזרת (callback)

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

Chrome 99 ומעלה

הפרמטר callback נראה כך:
```
(response: any)=>void
```
- תשובה
  
  הכול
  
  הודעת התשובה שנשלחה על ידי המארח המקורי של העברת ההודעות. אם תתרחש שגיאה במהלך ההתחברות למארח של העברת ההודעות המותאמות, תתבצע קריאה חוזרת (callback) ללא ארגומנטים והסמל runtime.lastError יוגדר כהודעת שגיאה.

החזרות

מבטיח<any>

Chrome 99 ומעלה

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

setUninstallURL()

הבטחה

chrome.runtime.setUninstallURL(
  url: string,
  callback?: function,
)

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

פרמטרים

כתובת אתר

מחרוזת

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

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

Chrome 45 ואילך

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

החזרות

Promise<void>

Chrome 99 ומעלה

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

אירועים

onBrowserUpdateAvailable

הוצא משימוש

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

יש להשתמש ב-runtime.onRestartRequired.

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

פרמטרים

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

פונקציה

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

onConnect

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

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

פרמטרים

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

פונקציה

הפרמטר callback נראה כך:
```
(port: Port)=>void
```
- יציאה
  
  יציאה

onConnectExternal

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

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

פרמטרים

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

פונקציה

הפרמטר callback נראה כך:
```
(port: Port)=>void
```
- יציאה
  
  יציאה

onConnectNative

Chrome 76 ומעלה

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

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

פרמטרים

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

פונקציה

הפרמטר callback נראה כך:
```
(port: Port)=>void
```
- יציאה
  
  יציאה

onInstalled

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

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

פרמטרים

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

פונקציה

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

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

פרמטרים

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

פונקציה

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

onSuspendCanceled

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

נשלח אחרי onPause כדי לציין שטעינת האפליקציה לא תוסר.

פרמטרים

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

פונקציה

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

onUpdateAvailable

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

מופעל כשיש עדכון זמין, אבל לא מותקן באופן מיידי כי האפליקציה פועלת כרגע. אם לא תבצעו שום פעולה, העדכון יותקן בפעם הבאה שטעינת דף הרקע תבוטל. אם תרצו שהוא יותקן מוקדם יותר, תוכלו לקרוא במפורש ל-chrome.runtime.reload() . אם התוסף משתמש בדף רקע קבוע, כמובן שטעינה של דף הרקע לעולם לא תבוצע באופן ידני. לכן, אלא אם תתבצע קריאה ידנית ל-chrome.runtime.reload() בתגובה לאירוע הזה, העדכון לא יותקן מחדש עד הפעם הבאה ש-Chrome עצמו יותקן מחדש. אם אין handlers שמאזינים לאירוע הזה, ולתוסף יש דף רקע קבוע, ההתנהגות שלו תהיה זהה להפעלה של 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