chrome.debugger

תיאור

‫chrome.debugger API משמש כהעברה חלופית לפרוטוקול לניפוי באגים מרחוק של Chrome. אפשר להשתמש ב-chrome.debugger כדי לצרף כרטיסייה אחת או יותר למכשיר, כדי לבצע אינטראקציה עם הרשת, לנפות באגים ב-JavaScript, לשנות את ה-DOM ואת ה-CSS ועוד. משתמשים במאפיין Debuggee‏ tabId כדי לטרגט כרטיסיות באמצעות sendCommand ולנתב אירועים לפי tabId מתוך קריאות חוזרות (callback) של onEvent.

הרשאות

debugger

הערת אבטחה

מסיבות אבטחה, ה-API‏ chrome.debugger לא מספק גישה לכל הדומיינים של פרוטוקול כלי הפיתוח ל-Chrome. הדומיינים הזמינים הם: Accessibility, Audits, CacheStorage, Console, CSS, Database, Debugger, DOM, DOMDebugger, DOMSnapshot, Emulation, Fetch, IO, Input, Inspector, Log, Network, Overlay, Page, Performance, Profiler, Runtime, Storage, Target, Tracing, WebAudio

מניפסט

כדי להשתמש ב-API הזה, צריך להצהיר על ההרשאה "debugger" במניפסט של התוסף.

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

דוגמאות

כדי לנסות את ה-API הזה, מתקינים את דוגמת ה-API של כלי הניפוי באגים ממאגר chrome-extension-samples.

סוגים

Debuggee

מזהה של תוכנה לניפוי באגים. צריך לציין tabId, ‏ extensionId או targetId

מאפיינים

  • extensionId

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

    המזהה של התוסף שרוצים לבצע בו ניפוי באגים. אפשר לצרף לדף הרקע של תוסף רק כשמשתמשים במתג --silent-debugger-extension-api של שורת הפקודה.

  • tabId

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

    המזהה של הכרטיסייה שרוצים לנפות בה באגים.

  • targetId

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

    המזהה האטום של יעד ניפוי הבאגים.

DebuggerSession

‫Chrome 125 ואילך

מזהה הסשן של ניפוי הבאגים. צריך לציין את אחד מהערכים tabId, ‏ extensionId או targetId. בנוסף, אפשר לספק sessionId אופציונלי. אם sessionId מצוין בארגומנטים שנשלחים מ-onEvent, המשמעות היא שהאירוע מגיע מסשן של פרוטוקול צאצא בסשן של פרוטוקול המאגר (root). אם מציינים את sessionId כשמעבירים אותו אל sendCommand, הוא מכוון לסשן של פרוטוקול צאצא בתוך סשן הניפוי באגים של השורש.

מאפיינים

  • extensionId

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

    המזהה של התוסף שרוצים לבצע בו ניפוי באגים. אפשר לצרף לדף הרקע של תוסף רק כשמשתמשים במתג --silent-debugger-extension-api של שורת הפקודה.

  • sessionId

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

    המזהה האטום של הסשן של פרוטוקול כלי הפיתוח ל-Chrome. מזהה סשן צאצא בסשן השורש שמזוהה על ידי tabId, ‏ extensionId או targetId.

  • tabId

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

    המזהה של הכרטיסייה שרוצים לנפות בה באגים.

  • targetId

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

    המזהה האטום של יעד ניפוי הבאגים.

DetachReason

‫Chrome 44 ואילך

הסיבה לסיום החיבור.

Enum

‫"target_closed"

"canceled_by_user"

TargetInfo

מידע על יעד ניפוי הבאגים

מאפיינים

  • מצורף

    בוליאני

    הערך הוא True אם מאתר הבאגים כבר מצורף.

  • extensionId

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

    מזהה התוסף, מוגדר אם type = 'background_page'.

  • faviconUrl

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

    כתובת ה-URL של סמל האתר של היעד.

  • id [מזהה]

    מחרוזת

    מזהה היעד.

  • tabId

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

    מזהה הכרטיסייה, מוגדר אם type == 'page'.

  • title

    מחרוזת

    כותרת דף היעד.

  • סוג היעד.

  • כתובת אתר

    מחרוזת

    כתובת היעד.

TargetInfoType

‫Chrome 44 ואילך

סוג היעד.

Enum

‫"page"

‎"background_page"

‎"worker"

‫"other"

Methods

attach()

Promise 
chrome.debugger.attach(
  target: Debuggee,
  requiredVersion: string,
  callback?: function,
): Promise<void>

מצרף את מאתר הבאגים ליעד שצוין.

פרמטרים

  • יעד

    Debuggee

    יעד הניפוי באגים שאליו רוצים לצרף.

  • requiredVersion

    מחרוזת

    גרסת פרוטוקול הניפוי הבאגים הנדרשת ('0.1'). אפשר לצרף רק ל-debuggee עם גרסה ראשית תואמת וגרסה משנית גדולה או שווה. כאן אפשר לראות את רשימת גרסאות הפרוטוקול.

  • callback

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

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

    () => void

החזרות

  • Promise<void>

    ‫Chrome 96 ואילך

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

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

detach()

Promise 
chrome.debugger.detach(
  target: Debuggee,
  callback?: function,
): Promise<void>

מנתק את מאתר הבאגים מהיעד הנתון.

פרמטרים

  • יעד

    Debuggee

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

  • callback

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

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

    () => void

החזרות

  • Promise<void>

    ‫Chrome 96 ואילך

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

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

getTargets()

Promise 
chrome.debugger.getTargets(
  callback?: function,
): Promise<TargetInfo[]>

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

פרמטרים

  • callback

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

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

    (result: TargetInfo[]) => void

    • תוצאה

      TargetInfo[]

      מערך של אובייקטים מסוג TargetInfo שמתאים ליעדי הניפוי באגים הזמינים.

החזרות

  • Promise<TargetInfo[]>

    ‫Chrome 96 ואילך

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

sendCommand()

Promise 
chrome.debugger.sendCommand(
  target: DebuggerSession,
  method: string,
  commandParams?: object,
  callback?: function,
): Promise<object | undefined>

שליחת הפקודה שצוינה ליעד הניפוי.

פרמטרים

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

  • method

    מחרוזת

    שם ה-method. צריך לבחור אחת מהשיטות שמוגדרות בפרוטוקול לניפוי באגים מרחוק.

  • commandParams

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

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

  • callback

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

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

    (result?: object) => void

    • תוצאה

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

      אובייקט JSON עם התגובה. המבנה של התשובה משתנה בהתאם לשם השיטה, והוא מוגדר על ידי המאפיין 'returns' בתיאור הפקודה בפרוטוקול של ניפוי הבאגים מרחוק.

החזרות

  • Promise<object | undefined>

    ‫Chrome 96 ואילך

    גוף התשובה. אם מתרחשת שגיאה במהלך פרסום ההודעה, ההבטחה תידחה.

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

אירועים

onDetach

chrome.debugger.onDetach.addListener(
  callback: function,
)

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

פרמטרים

onEvent

chrome.debugger.onEvent.addListener(
  callback: function,
)

מופעל בכל פעם שמתרחש אירוע של מכשור לבעיות בניפוי באגים ביעד.

פרמטרים

  • callback

    פונקציה

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

    (source: DebuggerSession, method: string, params?: object) => void

    • method

      מחרוזת

    • params

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