chrome.debugger

תיאור

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

הרשאות

debugger

הערת אבטחה

מטעמי אבטחה, ה-API של chrome.debugger לא מספק גישה לכל כלי הפיתוח ל-Chrome דומיינים של פרוטוקול. הדומיינים הזמינים הם: נגישות, ביקורות, CacheStorage, Console, CSS, מסד נתונים, כלי לניפוי באגים, DOM, DOMDebugger, DOMSnapshot, אמולציה, אחזור, IO, קלט, מפקח, יומן, רשת, שכבת על, דף, ביצועים, Profiler, זמן ריצה, אחסון, יעד, מעקב, WebAudio ו-WebAuthn.

מניפסט

כדי להשתמש ב-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 מצוין לארגומנטים שנשלחים מ-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

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

מאפיינים

  • מצורף

    בוליאני

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

  • extensionId

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

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

  • faviconUrl

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

    כתובת ה-URL של סמל האתר בקמפיין.

  • id [מזהה]

    מחרוזת

    מזהה היעד.

  • tabId

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

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

  • title

    מחרוזת

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

  • סוג היעד.

  • כתובת אתר

    מחרוזת

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

TargetInfoType

Chrome 44 ואילך

סוג היעד.

Enum

"דף"

"background_page"

"worker"

"אחר"

שיטות

attach()

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

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

פרמטרים

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

  • requiredVersion

    מחרוזת

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

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

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

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

    () => void

החזרות

  • הבטחה<Empty>

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

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

detach()

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

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

פרמטרים

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

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

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

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

    () => void

החזרות

  • הבטחה<Empty>

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

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

getTargets()

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

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

פרמטרים

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

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

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

    (result: TargetInfo[]) => void

    • תוצאה

      TargetInfo[]

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

החזרות

  • Promise&lt;TargetInfo[]&gt;

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

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

sendCommand()

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

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

פרמטרים

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

  • method

    מחרוזת

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

  • commandParams

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

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

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

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

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

    (result?: object) => void

    • תוצאה

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

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

החזרות

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

    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

      מחרוזת

    • פרמטרים

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