chrome.debugger

תיאור

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

הרשאות

debugger

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

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

הערה

מטעמי אבטחה, ה-API chrome.debugger לא מאפשר גישה לכל הדומיינים של הפרוטוקולים של כלי הפיתוח ל-Chrome. הדומיינים הזמינים הם: Accessibility, DOMDebugger, DOMSnapshot, DOMSnapshot, DOMSnapshot, Database, Database, DOM, DOMDebugger, DOMSnapshot, DOMSnapshotCacheStorageWebAudioWebAuthn

דוגמאות

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

סוגים

Debuggee

מזהה של ניפוי באגים. יש לציין TabId, extensionId או targetId

תכונות

  • extensionId

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

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

  • tabId

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

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

  • targetId

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

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

DebuggerSession

בהמתנה

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

תכונות

  • extensionId

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

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

  • sessionId

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

    המזהה האטום של הסשן של פרוטוקול Chrome DevTools. משמש לזיהוי של סשן צאצא בתוך סשן הבסיס שזוהה באמצעות TabId, extensionId או targetId.

  • tabId

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

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

  • targetId

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

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

DetachReason

Chrome 44 ואילך

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

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

"target_closed"

"canceled_by_user"

TargetInfo

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

תכונות

  • מחובר

    boolean

    True אם הכלי לניפוי באגים כבר מצורף.

  • extensionId

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

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

  • faviconUrl

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

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

  • id

    string

    מזהה יעד.

  • tabId

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

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

  • title

    string

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

  • סוג היעד.

  • כתובת אתר

    string

    כתובת ה-URL של היעד.

TargetInfoType

Chrome 44 ואילך

סוג היעד.

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

"background_page"

"worker"

שיטות

attach()

הבטחה 
chrome.debugger.attach(
  target: Debuggee,
  requiredVersion: string,
  callback?: function,
)

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

פרמטרים

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

  • requiredVersion

    string

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

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

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

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

    ()=>void

החזרות

  • Promise<void>

    Chrome 96 ומעלה

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

detach()

הבטחה 
chrome.debugger.detach(
  target: Debuggee,
  callback?: function,
)

ניתוק של הכלי לניפוי באגים מהיעד הנתון.

פרמטרים

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

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

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

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

    ()=>void

החזרות

  • Promise<void>

    Chrome 96 ומעלה

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

getTargets()

הבטחה 
chrome.debugger.getTargets(
  callback?: function,
)

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

פרמטרים

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

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

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

    (result: TargetInfo[])=>void

    • תוצאה אחת

      TargetInfo[]

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

החזרות

  • Promise<TargetInfo[]>

    Chrome 96 ומעלה

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

sendCommand()

הבטחה 
chrome.debugger.sendCommand(
  target: DebuggerSession,
  method: string,
  commandParams?: object,
  callback?: function,
)

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

פרמטרים

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

  • method

    string

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

  • commandParams

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

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

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

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

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

    (result?: object)=>void

    • תוצאה אחת

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

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

החזרות

  • Promise<object|undefined>

    Chrome 96 ומעלה

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

אירועים

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

      string

    • params

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