תיאור
אפשר להשתמש ב-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
מסנן להתאמה לפי הקשרים מסוימים של תוספים. ההקשרים התואמים חייבים להתאים לכל המסננים שצוינו. כל מסנן שלא צוין תואם לכל ההקשרים הזמינים. לכן, מסנן של '{}' יתאים לכל ההקשרים הזמינים.
תכונות
-
contextIds
string[] אופציונלי
-
contextTypes
ContextType[] אופציונלי
-
documentIds
string[] אופציונלי
-
documentOrigins
string[] אופציונלי
-
documentUrls
string[] אופציונלי
-
frameIds
number[] אופציונלי
-
גלישה פרטית
בוליאני אופציונלי
-
tabIds
number[] אופציונלי
-
windowIds
number[] אופציונלי
ContextType
טיפוסים בני מנייה (enum)
"TAB"
מציין את סוג ההקשר ככרטיסייה
"POPUP"
מציין את סוג ההקשר כחלון קופץ של תוסף
"BACKGROUND"
קביעת סוג ההקשר בתור קובץ שירות (service worker).
"OFFSCREEN_DOCUMENT"
מציין את סוג ההקשר כמסמך מחוץ למסך.
"SIDE_PANEL"
מציין את סוג ההקשר כחלונית צדדית.
ExtensionContext
הקשר שמארח תוכן של תוסף.
תכונות
-
contextId
string
מזהה ייחודי להקשר הזה
-
contextType
סוג ההקשר שאליו התוכן מתייחס.
-
documentId
מחרוזת אופציונלי
מזהה ייחודי אוניברסלי (UUID) של המסמך המשויך להקשר הזה, או לא מוגדר אם ההקשר מתארח לא במסמך.
-
documentOrigin
מחרוזת אופציונלי
מקור המ��מך המשויך להקשר הזה, או לא מוגדר אם ההקשר לא מתארח במסמך.
-
documentUrl
מחרוזת אופציונלי
כתובת ה-URL של המסמך המשויך להקשר הזה, או לא מוגדר אם ההקשר לא מתארח במסמך.
-
frameId
number
מזהה המסגרת עב��ר ההקשר הזה. או 1- אם ההקשר לא מתארח במסגרת.
-
גלישה פרטית
boolean
האם ההקשר משויך לפרופיל פרטי.
-
tabId
number
מזהה הכרטיסייה להקשר הזה או 1- אם ההקשר לא מתארח בכרטיסייה.
-
windowId
number
מזהה החלון להקשר הזה או -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
הסיבה שהאירוע הזה נשלח.
טיפוסים בני מנייה (enum)
"install"
מציין את סיבת האירוע כהתקנה.
"update"
מציין את סיבת האירוע כעדכון של תוסף.
"chrome_update"
מציין את הסיבה לאירוע כעדכון של Chrome.
"shared_module_update"
מציין את סיבת האירוע כעדכון למודול משותף.
OnRestartRequiredReason
הסיבה לשליחת האירוע. הערך 'app_update' משמש כאשר יש צורך בהפעלה מחדש כי האפליקציה מעודכנת לגרסה חדשה יותר. צריך להשתמש ב-'os_update' כשצריך להפעיל מחדש כי הדפדפן/מערכת ההפעלה מעודכנים לגרסה חדשה יותר. הערך 'תקופתי' משמש אם המערכת פועלת במשך יותר מזמן הפעולה התקינה המותר במדיניות הארגון.
טיפוסים בני מנייה (enum)
'app_update'
מציין את סיבת האירוע כעדכון לאפליקציה.
"os_update"
מציין את סיבת האירוע כעדכון של מערכת ההפעלה.
"periodic"
מציין את סיבת האירוע כהפעלה תקופתית מחדש של האפליקציה.
PlatformArch
ארכיטקטורת המעבד של המחשב.
טיפוסים בני מנייה (enum)
"זרוע"
הגדרה של ארכיטקטורת תהליך לעיבוד כזרוע.
"arm64"
הגדרה של ארכיטקטורת העיבוד (gclouder) כ-Arm64.
"x86-32"
מגדיר את ארכיטקטורת העיבוד כ-x86-32.
'x86-64'
ההגדרה של ארכיטקטורת העיבוד (CPU) מוגדרת כ-x86-64.
"mips"
הגדרה של ארכיטקטורת תהליך לעיבוד כ-Mips.
"mips64"
מגדיר את ארכיטקטורת העיבוד כ-mips64.
PlatformInfo
אובייקט שמכיל מידע על הפלטפורמה הנוכחית.
תכונות
-
קשת
ארכיטקטורת המעבד של המחשב.
-
nacl_arch
ארכיטקטורת הלקוח המקורית. זה עשוי להיות שונה מ'קשת' בפלטפורמות מסוימות.
-
os
מערכת ההפעלה Chrome פועלת במערכת.
PlatformNaclArch
ארכיטקטורת הלקוח המקורית. זה עשוי להיות שונה מ'קשת' בפלטפורמות מסוימות.
טיפוסים בני מנייה (enum)
"arm"
הגדרת ארכיטקטורת הלקוח הנייטיב כזרוע.
"x86-32"
ההגדרה קובעת את ארכיטקטורת הלקוח המקורית כ-x86-32.
"x86-64"
ההגדרה קובעת את ארכיטקטורת הלקוח המקורית כ-x86-64.
"mips"
הגדרת ארכיטקטורת לקוח נייטיב כ-Mips.
"mips64"
מגדיר את ארכיטקטורת הלקוח המקורית כ-mips64.
PlatformOs
מערכת ההפעלה Chrome פועלת במערכת.
טיפוסים בני מנייה (enum)
"mac"
מציין את מערכת ההפעלה MacOS.
"win"
מציין את מערכת ההפעלה Windows.
"android"
מציין את מערכת ההפעלה Android.
"cros"
מציין את מערכת ההפעלה של Chrome.
"linux"
מציין את מערכת ההפעלה Linux.
"openbsd"
מציין את מערכת ההפעלה OpenBSD.
"פוקסיה"
מציין את מערכת ההפעלה של Fuchsia.
Port
אובייקט שמאפשר תקשורת דו-כיוונית עם דפים אחרים. מידע נוסף זמין בקטע חיבורים לטווח ארוך.
תכונות
-
name
string
שם השקע, כפי שצוין בשיחה אל
runtime.connect
. -
onDisconnect
אירוע<functionvoidvoid>
מופעל כשהיציאה מנותקת מהקצה השני. אפשר להגדיר את הפרמטר
runtime.lastError
א�� השקע נותק בגלל שגיאה. אם השקע נסגר דרך ניתוק, האירוע הזה יופעל רק בצד השני. האירוע הזה מופעל פעם אחת לכל היותר (ניתן לעיין גם בקטע משך החיים של יציאה).הפונקציה
onDisconnect.addListener
נראית כך:(callback: function) => {...}
-
onMessage
אירוע<functionvoidvoid>
האירוע הזה מופעל כשמתבצעת קריאה ל-postMessage בצד השני של היציאה.
הפונקציה
onMessage.addListener
נראית כך:(callback: function) => {...}
-
שולח
MessageSender אופציונלי
המאפיין הזה יופיע רק ביציאות שהועברו למאזינים של onConnect / onConnectExternal / onConnectNative.
-
ניתוק
void
צריך לנתק מיד את השקע. קריאה ל-
disconnect()
ביציאה שכבר מנותקת לא משפיעה. לאחר ניתוק שקע, לא יישלחו אירועים חדשים ליציאה הזו.הפונקציה
disconnect
נראית כך:() => {...}
-
postMessage
void
שולחים הודעה לצד השני של היציאה. אם השקע מנותק, תופיע הודעת שגיאה.
הפונקציה
postMessage
נראית כך:(message: any) => {...}
-
הודעה
הכול
Chrome 52 ומעלהההודעה שיש לשלוח. האובייקט הזה צריך להיות ניתן ל-JSON.
-
RequestUpdateCheckStatus
התוצאה של בדיקת העדכונים
טיפוסים בני מנייה (enum)
"throttled"
מציין שבדיקת הסטטוס עברה ויסות נתונים. מצב כזה יכול לקרות אחרי בדיקות חוזרות בפרק זמן קצר.
"no_update"
מציין שאין עדכונים זמינים להתקנה.
"update_available"
מציין שיש עדכון זמין להתקנה.
תכונות
id
ה��זהה ��ל ��ת��סף/האפליקציה.
סוג
string
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"
. למידע נוסף, אפשר לעיין במאמר העברת הודעות מקומית.
פרמטרים
-
יישום
string
השם של האפליקציה הרשומה שאליה רוצים להתחבר.
החזרות
-
יציאה שדרכם ניתן לשלוח ולקבל הודעות באמצעות האפליקציה
getBackgroundPage()
chrome.runtime.getBackgroundPage(
callback?: function,
)
מאחזר את אובייקט 'חלון' של JavaScript של דף הרקע שפועל בתוך התוסף/האפליקציה הנוכחיים. אם דף הרקע הוא דף אירוע, המערכת תוודא שהוא נטען לפני הקריאה החוזרת (callback). אם אין דף רקע, מוגדרת שגיאה.
פרמטרים
-
קריאה חוזרת (callback)
פונקציה אופציונלי
הפרמטר
callback
נראה כך:(backgroundPage?: Window) => void
-
backgroundPage
חלון אופציונלי
אובייקט 'חלון' של JavaScript עבור דף הרקע.
-
החזרות
-
Promise<Window | undefined>
Chrome 99 ומעלהיש תמיכה בהבטחות במניפסט מגרסה V3 ואילך, אבל אפשר לבצע קריאה חוזרת (callback) לצורך תאימות לאחור. אי אפשר להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה מסתיימת עם אותו הסוג שמועבר לקריאה החוזרת.
getContexts()
chrome.runtime.getContexts(
filter: ContextFilter,
callback?: function,
)
מאחזר מידע על ��קשרים פעילים המשויכים לתוסף הזה
פרמטרים
-
סינון
מסנן לאיתור הקשרים תואמים. הקשר מסוים תואם אם הוא תואם לכל השדות שצוינו במסנן. כל שדה שלא צוין במסנן תואם לכל ההקשרים.
-
קריאה חוזרת (callback)
פונקציה אופציונלי
הפרמטר
callback
נראה כך:(contexts: ExtensionContext[]) => void
-
הקשרים
ההקשרים התואמים, אם יש.
-
החזרות
-
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
-
החזרות
-
Promise<PlatformInfo>
Chrome 99 ומעלהיש תמיכה בהבטחות במניפסט מגרסה V3 ואילך, אבל אפשר לבצע קריאה חוזרת (callback) לצורך תאימות לאחור. אי אפשר להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה מסתיימת עם אותו הסוג שמועבר לקריאה החוזרת.
getURL()
chrome.runtime.getURL(
path: string,
)
ממיר נתיב יחסי בתוך ספריית התקנה של אפליקציה/תוסף לכתובת URL המוגדרת במלואה.
פרמטרים
-
נתיב
string
נתיב למשאב בתוך אפליקציה/תוסף, מבוטא ביחס לספריית ההתקנה שלו.
החזרות
-
string
כתובת ה-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
התוצאה של בדיקת העדכונים
-
גרסה
מחרוזת אופציונלי
אם יש עדכון זמין, היא מכילה את הגרסה של העדכון הזמין.
-
-
החזרות
-
Promise<object>
Chrome 109 ומעלהיש תמיכה בהבטחות במניפסט מגרסה V3 ואילך, אבל אפשר לבצע קריאה חוזרת (callback) לצורך תאימות לאחור. אי אפשר להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה מסתיימת עם אותו הסוג שמועבר לקריאה החוזרת.
restart()
chrome.runtime.restart()
כשהאפליקציה פועלת במצב קיוסק, צריך להפעיל מחדש את מכשיר ChromeOS. אחרת אין אפשרות להפעיל אותו.
restartAfterDelay()
chrome.runtime.restartAfterDelay(
seconds: number,
callback?: function,
)
צריך להפעיל מחדש את מכשיר ChromeOS כשהאפליקציה תפעל במצב קיוסק אחרי מספר השניות הנתון. אם תתקשרו שוב לפני סיום הזמן, ההפעלה מחדש תתעכב. אם קוראים לערך 1-, ההפעלה מחדש תבוטל. במצב שלא במצב קיוסק, אין אפשרות להפעיל אותו. רק התוסף הראשון יכול להפעיל את ה-API הזה שוב ושוב.
פרמטרים
-
שניות
number
הזמן להמתין בשניות לפני הפעלה מחדש של המכשיר, או 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"
.
פרמטרים
-
יישום
string
השם של המארח המקומי להעברת הודעות.
-
הודעה
אובייקט
ההודעה שתועבר למארח המקורי של העברת ההודעות.
-
קריאה חוזרת (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 תווים לכל היותר.
פרמטרים
-
כתובת אתר
string
כתובת 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
).
onConnectExternal
chrome.runtime.onConnectExternal.addListener(
callback: function,
)
מופעלת כשנוצר חיבור מתוסף אחר (על ידי runtime.connect
) או מאתר אינטרנט שניתן לחבר אותו באופן חיצוני.
onConnectNative
chrome.runtime.onConnectNative.addListener(
callback: function,
)
מופעל כשנוצר חיבור מאפליקציה מקורית. לאירוע הזה נדרשת ההרשאה "nativeMessaging"
. הוא נתמך רק במערכת ההפעלה של Chrome.
onInstalled
chrome.runtime.onInstalled.addListener(
callback: function,
)
מופעל כשהתוסף מותקן לראשונה, כשמתבצע עדכון של התוסף לגרסה חדשה, וכשמתבצע עדכון של Chrome לגרסה חדשה.
פרמטרים
-
קריאה חוזרת (callback)
פונקציה
הפרמטר
callback
נראה כך:(details: object) => void
-
פרטים
אובייקט
-
id
מחרוזת אופציונלי
מציין את המזהה של תוסף המודול המשותף שיובא, שעודכן. הערך הזה מופיע רק אם 'reason' הוא 'shared_module_update'.
-
previousVersion
מחרוזת אופציונלי
מציין את הגרסה הקודמת של התוסף, שזה עתה עודכנה. הערך הזה מוצג רק אם 'סיבה' היא 'עדכון'.
-
סיבה
הסיבה שהאירוע הזה נשלח.
-
-
onMessage
chrome.runtime.onMessage.addListener(
callback: function,
)
מופעל כשהודעה נשלחת מתהליך תוסף (על ידי runtime.sendMessage
) או מסקריפט תוכן (על ידי tabs.sendMessage
).
פרמטרים
-
קריאה חוזרת (callback)
פונקציה
הפרמטר
callback
נראה כך:(message: any, sender: MessageSender, sendResponse: function) => boolean | undefined
-
הודעה
הכול
-
שולח
-
sendResponse
פונקציה
הפרמטר
sendResponse
נראה כך:() => void
-
החזרות
בוליאני | undefined
-
onMessageExternal
chrome.runtime.onMessageExternal.addListener(
callback: function,
)
מופעל כאשר הודעה נשלחת מתוסף אחר (על ידי runtime.sendMessage
). לא ניתן לשימוש בסקריפט תוכן.
פרמטרים
-
קריאה חוזרת (callback)
פונקציה
הפרמטר
callback
נראה כך:(message: any, sender: MessageSender, sendResponse: function) => boolean | undefined
-
הודעה
הכול
-
שולח
-
sendResponse
פונקציה
הפרמטר
sendResponse
נראה כך:() => void
-
החזרות
בוליאני | undefined
-
onRestartRequired
chrome.runtime.onRestartRequired.addListener(
callback: function,
)
מופעל כשצריך להפעיל מחדש אפליקציה או את המכשיר שבו הוא פועל. האפליקציה צריכה לסגור את כל החלונות שלה במועד הנוח ביותר כדי לאפשר להפעלה מחדש להתרחש. אם ��אפליקציה לא עושה דבר, תיאלץ הפעלה מחדש לאחר סיום תקופת חסד של 24 שעות. נכון לעכשיו, האירוע הזה מופעל רק באפליקציות "קיוסק" של ChromeOS.
פרמטרים
-
קריאה חוזרת (callback)
פונקציה
הפרמטר
callback
נראה כך:(reason: OnRestartRequiredReason) => void
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
-
פרטים
אובייקט
-
גרסה
string
מספר הגרסה של העדכון הזמין.
-
-
onUserScriptConnect
chrome.runtime.onUserScriptConnect.addListener(
callback: function,
)
מופעל כאשר נוצר חיבור מסקריפט של משתמש מהתוסף הזה.
onUserScriptMessage
chrome.runtime.onUserScriptMessage.addListener(
callback: function,
)
מופעל כשהודעה נשלחת מסקריפט של משתמש שמשויך לאותו תוסף.
פרמטרים
-
קריאה חוזרת (callback)
פונקציה
הפרמטר
callback
נראה כך:(message: any, sender: MessageSender, sendResponse: function) => boolean | undefined
-
הודעה
הכול
-
שולח
-
sendResponse
פונקציה
הפרמטר
sendResponse
נראה כך:() => void
-
החזרות
בוליאני | undefined
-