chrome.runtime

תיאור

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

סקירה כללית

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

העברת הודעות

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

הערה: מידע נוסף על הנושא זמין במאמר העברת הודעות.

גישה למטא-נתונים של תוספים ופלטפורמות

השיטות האלה מאפשרות לאחזר כמה קטעי מטא-נתונים ספציפיים לגבי התוסף והפלטפורמה. שיטות בקטגוריה הזו כוללות את getManifest() ואת getPlatformInfo().

ניהול מחזור החיים והאפשרויות של התוספים

המאפיינים האלה מאפשרים לבצע פעולות מטא מסוימות על התוסף ולהציג את דף האפשרויות. שיטות ואירועים בקטגוריה הזו כוללים את onInstalled,‏ onStartup,‏ openOptionsPage(),‏ reload()‎,‏ requestUpdateCheck() ו-setUninstallURL()‎.

כלי עזר

השיטות האלה מספקות שימושים שונים, כמו המרה של ייצוגים פנימיים של משאבים לפורמטים חיצוניים. שיטות בקטגוריה הזו כוללות את getURL()‎.

כלי עזר במצב קיוסק

השיטות האלה זמינות רק ב-ChromeOS, והן נועדו בעיקר לתמוך בהטמעות של קיוסקים. שיטות בקטגוריה הזו כוללות את restart ואת restartAfterDelay.

הרשאות

רוב השיטות ב-Runtime API לא דורשות הרשאה כלשהי, מלבד sendNativeMessage ו-connectNative, שדורשות את ההרשאה nativeMessaging.

מניפסט

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

manifest.json:

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

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

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

כדי שדף אינטרנט יוכל לגשת לנכס שמתארח בדומיין אחר, צריך לציין את כתובת ה-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);
});

background.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');
  }
});

דוגמאות לתוספים

דוגמאות נוספות לממשקי API בסביבת זמן ריצה מפורטות בהדגמה של Manifest V3 – משאבים שניתנים לגישה באינטרנט.

סוגים

ContextFilter

גרסה 114 ואילך של Chrome

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

מאפיינים

• contextIds

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

• contextTypes

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

• documentIds

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

• documentOrigins

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

• documentUrls

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

• frameIds

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

• מצב פרטי

  בוליאני אופציונלי

• tabIds

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

• windowIds

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

ContextType

גרסה 114 ואילך של Chrome

Enum

"TAB"
ציון סוג ההקשר ככרטיסייה

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

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

"OFFSCREEN_DOCUMENT"
הערך הזה מציין שסוג ההקשר הוא מסמך מחוץ למסך.

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

‎"DEVELOPER_TOOLS" הערך הזה מציין שסוג ההקשר הוא 'כלים למפתחים'.

ExtensionContext

גרסה 114 ואילך של Chrome

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

מאפיינים

• contextId

  מחרוזת

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

• contextType

  ContextType

  סוג ההקשר שאליו הנתון הזה תואם.

• documentId

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

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

• documentOrigin

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

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

• documentUrl

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

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

• frameId

  number

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

• מצב פרטי

  בוליאני

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

• tabId

  number

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

• windowId

  number

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

MessageSender

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

מאפיינים

• documentId

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

  גרסה 106 ואילך של Chrome

  מזהה UUID של המסמך שדרכו נפתח החיבור.

• documentLifecycle

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

  גרסה 106 ואילך של Chrome

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

• frameId

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

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

• id [מזהה]

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

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

• nativeApplication

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

  Chrome מגרסה 74 ואילך

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

• מקור

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

  גרסה 80 ואילך של Chrome

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

• כרטיסייה

  Tab אופציונלי

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

• tlsChannelId

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

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

• כתובת אתר

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

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

OnInstalledReason

גרסה 44 ואילך של Chrome

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

Enum

‎"install"
הסיבה לאירוע היא התקנה.

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

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

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

OnRestartRequiredReason

גרסה 44 ואילך של Chrome

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

Enum

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

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

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

PlatformArch

גרסה 44 ואילך של Chrome

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

Enum

‎"arm"
מציין את ארכיטקטורת המעבד כ-arm.

‎"arm64"
מציינת את ארכיטקטורת המעבד כ-arm64.

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

‎"x86-64"
מציין את ארכיטקטורת המעבד כ-x86-64.

"mips"
הערך הזה מציין את ארכיטקטורת המעבד כ-mips.

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

PlatformInfo

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

מאפיינים

• קשת

  PlatformArch

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

• nacl_arch

  PlatformNaclArch

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

• os

  PlatformOs

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

PlatformNaclArch

גרסה 44 ואילך של Chrome

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

Enum

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

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

"x86-64"
הגדרת הארכיטקטורה של הלקוח המקורי כ-x86-64.

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

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

PlatformOs

גרסה 44 ואילך של Chrome

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

Enum

‎"mac"
מציינת את מערכת ההפעלה macOS.

"win"
מציינת את מערכת ההפעלה Windows.

‎"android"
מציינת את מערכת ההפעלה Android.

'cros'
מציינת את מערכת ההפעלה של Chrome.

‎"linux"
מציינת את מערכת ההפעלה Linux.

‎"openbsd"
מציינת את מערכת ההפעלה OpenBSD.

‎"fuchsia"
מציין את מערכת ההפעלה Fuchsia.

Port

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

מאפיינים

• שם

  מחרוזת

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

• onDisconnect

  Event<functionvoidvoid>

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

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

גרסה 44 ואילך של Chrome

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

Enum

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

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

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

מאפיינים

id

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

סוג

מחרוזת

lastError

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

סוג

אובייקט

מאפיינים

• הודעה

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

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

Methods

connect()

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

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

פרמטרים

• extensionId

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

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

• connectInfo

  אובייקט אופציונלי

  • includeTlsChannelId

    בוליאני אופציונלי

    האם מזהה ערוץ ה-TLS יועבר ל-onConnectExternal עבור תהליכים שמאזינים לאירוע החיבור.

  • שם

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

    יועבר ל-onConnect בתהליכים שמקשיבים לאירוע החיבור.

החזרות

• יציאה

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

connectNative()

chrome.runtime.connectNative(
  application: string,
)

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

פרמטרים

• יישום

  מחרוזת

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

החזרות

• יציאה

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

getBackgroundPage()

Promise חזית בלבד

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

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

פרמטרים

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

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

  הפרמטר callback נראה כך:

  (backgroundPage?: Window) => void

  • backgroundPage

    חלון אופציונלי

    אובייקט 'window' ב-JavaScript לדף הרקע.

החזרות

• Promise<Window | undefined>

  גרסה 99 ואילך של Chrome

  יש תמיכה ב-Promises רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.

getContexts()

Promise Chrome מגרסה 116 ואילך MV3 ואילך

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

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

פרמטרים

• סינון

  ContextFilter

  מסנן לאיתור הקשרים תואמים. הקשר תואם אם הוא תואם לכל השדות שצוינו במסנן. כל שדה לא מוגדר במסנן תואם לכל ההקשרים.

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

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

  הפרמטר callback נראה כך:

  (contexts: ExtensionContext[]) => void

  • הקשרים

    ExtensionContext[]

    ההקשרים התואמים, אם יש כאלה.

החזרות

• Promise<ExtensionContext[]>

  יש תמיכה ב-Promises רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.

getManifest()

chrome.runtime.getManifest()

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

החזרות

• אובייקט

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

getPackageDirectoryEntry()

Promise חזית בלבד

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

הפונקציה מחזירה DirectoryEntry לספריית החבילה.

פרמטרים

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

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

  הפרמטר callback נראה כך:

  (directoryEntry: DirectoryEntry) => void

  • directoryEntry

    DirectoryEntry

החזרות

• Promise<DirectoryEntry>

  Chrome מגרסה 122 ואילך

  יש תמיכה ב-Promises רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.

getPlatformInfo()

Promise

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

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

פרמטרים

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

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

  הפרמטר callback נראה כך:

  (platformInfo: PlatformInfo) => void

  • platformInfo

    PlatformInfo

החזרות

• Promise<PlatformInfo>

  גרסה 99 ואילך של Chrome

  יש תמיכה ב-Promises רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.

getURL()

chrome.runtime.getURL(
  path: string,
)

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

פרמטרים

• נתיב

  מחרוזת

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

החזרות

• מחרוזת

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

openOptionsPage()

Promise

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

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

ההתנהגות המדויקת עשויה להשתנות בהתאם למפתח options_ui או options_page במניפסט, או בהתאם ליכולות של Chrome באותו זמן. לדוגמה, הדף עשוי להיפתח בכרטיסייה חדשה, בכתובת chrome://extensions, באפליקציה או פשוט להתמקד בדף האפשרויות הפתוח. הוא אף פעם לא יגרום לטעינה מחדש של הדף של מבצע הקריאה החוזרת.

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

פרמטרים

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

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

  הפרמטר callback נראה כך:

  () => void

החזרות

• Promise<void>

  גרסה 99 ואילך של Chrome

  יש תמיכה ב-Promises רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.

reload()

chrome.runtime.reload()

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

requestUpdateCheck()

Promise

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

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

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

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

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

פרמטרים

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

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

  הפרמטר callback נראה כך:

  (result: object) => void

  • תוצאה

    אובייקט

    Chrome מגרסה 109 ואילך

    אובייקט RequestUpdateCheckResult שמכיל את סטטוס בדיקת העדכון ואת כל פרטי התוצאה, אם יש עדכון זמין

    • status

      RequestUpdateCheckStatus

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

    • גרסה

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

      אם יש עדכון זמין, כאן תופיע הגרסה של העדכון הזמין.

החזרות

• Promise<object>

  Chrome מגרסה 109 ואילך

  יש תמיכה ב-Promises רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.

restart()

chrome.runtime.restart()

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

restartAfterDelay()

Promise Chrome מגרסה 53 ואילך

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

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

פרמטרים

• שניות

  number

  משך ההמתנה בשניות לפני הפעלת המכשיר מחדש, או -1 כדי לבטל הפעלה מחדש מתוזמנת.

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

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

  הפרמטר callback נראה כך:

  () => void

החזרות

• Promise<void>

  גרסה 99 ואילך של Chrome

  יש תמיכה ב-Promises רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.

sendMessage()

Promise

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

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

פרמטרים

• extensionId

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

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

• הודעה

  כל

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

• אפשרויות

  אובייקט אופציונלי

  • includeTlsChannelId

    בוליאני אופציונלי

    האם מזהה ערוץ ה-TLS יועבר ל-onMessageExternal עבור תהליכים שמאזינים לאירוע החיבור.

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

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

  גרסה 99 ואילך של Chrome

  הפרמטר callback נראה כך:

  (response: any) => void

  • תשובה

    כל

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

החזרות

• Promise<any>

  גרסה 99 ואילך של Chrome

  יש תמיכה ב-Promises רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.

sendNativeMessage()

Promise

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

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

פרמטרים

• יישום

  מחרוזת

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

• הודעה

  אובייקט

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

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

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

  גרסה 99 ואילך של Chrome

  הפרמטר callback נראה כך:

  (response: any) => void

  • תשובה

    כל

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

החזרות

• Promise<any>

  גרסה 99 ואילך של Chrome

  יש תמיכה ב-Promises רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.

setUninstallURL()

Promise

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

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

פרמטרים

• כתובת אתר

  מחרוזת

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

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

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

  Chrome מגרסה 45 ואילך

  הפרמטר callback נראה כך:

  () => void

החזרות

• Promise<void>

  גרסה 99 ואילך של Chrome

  יש תמיכה ב-Promises רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.

אירועים

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

פרמטרים

• קריאה חוזרת (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'.

    • סיבה

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

פרמטרים

• קריאה חוזרת (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

גרסה 115 ואילך של Chrome גרסה MV3 ואילך של MV3

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

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

פרמטרים

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

  פונקציה

  הפרמטר callback נראה כך:

  (port: Port) => void

  • יציאה

    יציאה

onUserScriptMessage

גרסה 115 ואילך של Chrome גרסה MV3 ואילך של MV3

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

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

פרמטרים

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

  פונקציה

  הפרמטר callback נראה כך:

  (message: any, sender: MessageSender, sendResponse: function) => boolean | undefined

  • הודעה

    כל

  • שולח

    MessageSender

  • sendResponse

    פונקציה

    הפרמטר sendResponse נראה כך:

    () => void

  • החזרות

    boolean | undefined