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, ו-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 אופציונלי. אם sessionId מצוין בארגומנטים שנשלחים מ-onEvent, המשמעות היא שהאירוע מגיע מסשן של פרוטוקול צאצא בסשן של שורש ה-debuggee. אם מציינים sessionId כשמעבירים אותו אל sendCommand, הוא מכוון לסשן פרוטוקול צאצא בתוך סשן הניפוי של שורש ה-debuggee.

מאפיינים

  • extensionId

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

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

  • sessionId

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

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

  • tabId

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

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

  • targetId

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

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

DetachReason

‫Chrome 44 ואילך

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

Enum

‫"target_closed"

‫"canceled_by_user"

TargetInfo

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

מאפיינים

  • מצורף

    בוליאני

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

  • extensionId

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

    מזהה התוסף, מוגדר אם הסוג הוא '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 ואילך

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

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

detach()

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

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

פרמטרים

  • יעד

    Debuggee

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

  • callback

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

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

    () => void

החזרות

  • Promise<void>

    ‫Chrome 96 ואילך

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

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

getTargets()

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

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

פרמטרים

  • callback

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

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

    (result: TargetInfo[]) => void

    • תוצאה

      TargetInfo[]

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

החזרות

  • Promise<TargetInfo[]>

    ‫Chrome 96 ואילך

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

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 ואילך

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

    ההבטחות נתמכות רק ב-Manifest 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

      מחרוזת

    • פרמטרים

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