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

כאשר תוסף 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.

סוגים

ContextFilter

Chrome 114 ואילך

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

מאפיינים

• contextIds

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

• contextTypes

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

• documentIds

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

• documentOrigins

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

• documentUrls

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

• frameIds

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

• גלישה פרטית

  ערך בוליאני אופציונלי

• tabIds

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

• windowIds

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

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

  number

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

• גלישה פרטית

  בוליאני

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

• tabId

  number

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

• windowId

  number

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

MessageSender

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

מאפיינים

• documentId

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

  Chrome 106+

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

• documentLifecycle

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

  Chrome 106+

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

• frameId

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

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

• id [מזהה]

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

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

• nativeApplication

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

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

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

• מקור

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

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

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

• כרטיסייה

  Tab אופציונלי

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

• tlsChannelId

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

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

• כתובת אתר

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

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

OnInstalledReason

Chrome 44 ואילך

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

Enum

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

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

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

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

OnRestartRequiredReason

Chrome 44 ואילך

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

Enum

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

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

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

PlatformArch

Chrome 44 ואילך

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

Enum

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

"arm64"
הגדרת הארכיטקטורה של מעבדי המידע היא Arm64.

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

"x86-64"
הארכיטקטורה של מעבדי המידע היא x86-64.

"mips"
הגדרת הארכיטקטורה של מעבדי המידע היא מיילים.

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

PlatformInfo

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

מאפיינים

• קשת

  PlatformArch

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

• nacl_arch

  PlatformNaclArch

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

• מערכת הפעלה

  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"
מציין את מערכת ההפעלה Fuchsia.

Port

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

מאפיינים

• שם

  מחרוזת

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

• onDisconnect

  אירוע<functioncancelcancel>

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

  הפונקציה onDisconnect.addListener נראית כך:

  (callback: function) => {...}

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

    פונקציה

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

    (port: Port) => void

    • יציאה

      יציאה

• onMessage

  אירוע<functionpauseEmpty>

  האירוע הזה מופעל כשנשלחת קריאה ל-postMessage מהקצה השני של היציאה.

  הפונקציה onMessage.addListener נראית כך:

  (callback: function) => {...}

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

    פונקציה

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

    (message: any, port: Port) => void

    • הודעה

      כל

    • יציאה

      יציאה

• שולח

  MessageSender אופציונלי

  המאפיין הזה יוצג רק ביציאות שמועברות למאזינים של onConnect / onConnectExternal / onConnectNative.

• ניתוק

  ריק

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

  הפונקציה disconnect נראית כך:

  () => {...}

• postMessage

  ריק

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

  הפונקציה postMessage נראית כך:

  (message: any) => {...}

  • הודעה

    כל

    Chrome 52+

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

RequestUpdateCheckStatus

Chrome 44 ואילך

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

Enum

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

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

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

מאפיינים

id

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

סוג

מחרוזת

lastError

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

סוג

אובייקט

מאפיינים

• הודעה

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

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

שיטות

connect()

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

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

פרמטרים

• extensionId

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

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

• connectInfo

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

  • includeTlsChannelId

    ערך בוליאני אופציונלי

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

  • שם

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

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

החזרות

• יציאה

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

connectNative()

chrome.runtime.connectNative(
  application: string,
)

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

פרמטרים

• יישום

  מחרוזת

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

החזרות

• יציאה

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

getBackgroundPage()

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

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

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

פרמטרים

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

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

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

  (backgroundPage?: Window) => void

  • backgroundPage

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

    'חלון' של JavaScript לדף הרקע.

החזרות

• Promise&lt;Window | לא מוגדר>

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

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

getContexts()

הבטחה Chrome 116 ואילך MV3+

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

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

פרמטרים

• סינון

  ContextFilter

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

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

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

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

  (contexts: ExtensionContext[]) => void

  • ההקשרים

    ExtensionContext[]

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

החזרות

• Promise&lt;ExtensionContext[]&gt;

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

getManifest()

chrome.runtime.getManifest()

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

החזרות

• אובייקט

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

getPackageDirectoryEntry()

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

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

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

פרמטרים

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

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

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

  (directoryEntry: DirectoryEntry) => void

  • directoryEntry

    DirectoryEntry

החזרות

• Promise&lt;DirectoryEntry&gt;

  Chrome 122 ואילך

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

getPlatformInfo()

הבטחה

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

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

פרמטרים

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

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

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

  (platformInfo: PlatformInfo) => void

  • platformInfo

    PlatformInfo

החזרות

• Promise&lt;PlatformInfo&gt;

  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 לא יצר דף אפשרויות מסיבה אחרת, הקריאה החוזרת (callback) תגדיר את הדף lastError.

פרמטרים

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

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

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

  () => void

החזרות

• הבטחה<Empty>

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

    • status

      RequestUpdateCheckStatus

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

    • גרסה

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

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

החזרות

• Promise&lt;object&gt;

  Chrome 109+

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

restart()

chrome.runtime.restart()

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

restartAfterDelay()

הבטחה Chrome 53 ואילך

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

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

פרמטרים

• שניות

  number

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

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

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

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

  () => void

החזרות

• הבטחה<Empty>

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

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

sendMessage()

הבטחה

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)

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

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

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

  (response: any) => void

  • תשובה

    כל

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

החזרות

• הבטחה<כלשהו>

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

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

sendNativeMessage()

הבטחה

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

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

פרמטרים

• יישום

  מחרוזת

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

• הודעה

  אובייקט

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

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

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

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

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

  (response: any) => void

  • תשובה

    כל

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

החזרות

• הבטחה<כלשהו>

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

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

setUninstallURL()

הבטחה

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

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

פרמטרים

• כתובת אתר

  מחרוזת

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

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

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

  Chrome 45+

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

  () => void

החזרות

• הבטחה<Empty>

  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 [מזהה]

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

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

onMessageExternal

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

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

פרמטרים

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

  פונקציה

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

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

  • הודעה

    כל

  • שולח

    MessageSender

  • sendResponse

    פונקציה

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

    () => void

  • החזרות

    boolean | לא מוגדר

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

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

פרמטרים

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

  פונקציה

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

  () => void

onSuspendCanceled

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

נשלחת אחרי on suspended (השעיה) כדי לציין שטעינת האפליקציה לא תבוטל.

פרמטרים

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