chrome.debugger

תאריך הרענון: 2026-09-25 robots: noindex

תיאור

ממשק ה-API‏ chrome.debugger משמש כהעברה חלופית לפרוטוקול הניפוי באגים מרחוק של 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 הזה, מתקינים את הדוגמה של Debugger 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, הוא מכוון לסשן של פרוטוקול צאצא בתוך סשן האב של ניפוי הבאגים.

מאפיינים

  • extensionId

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

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

  • sessionId

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

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

  • tabId

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

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

  • targetId

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

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

DetachReason

‫Chrome 44 ואילך

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

ספירה

‫"target_closed"

"canceled_by_user"

TargetInfo

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

מאפיינים

  • מצורף

    בוליאני

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

  • extensionId

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

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

  • faviconUrl

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

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

  • id [מזהה]

    מחרוזת

    מזהה היעד.

  • tabId

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

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

  • title

    מחרוזת

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

  • סוג היעד.

  • url

    מחרוזת

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

TargetInfoType

‫Chrome 44 ואילך

סוג היעד.

ספירה

‫"page"

‫"background_page"

‫worker

'אחר'

Methods

attach()

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

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

פרמטרים

  • יעד

    Debuggee

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

  • requiredVersion

    מחרוזת

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

  • 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

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