תיאור
ה-API chrome.debugger
משמש כתעבורה חלופית לפרוטוקול לניפוי באגים מרחוק של Chrome. אפשר להשתמש ב-chrome.debugger
כדי לצרף כרטיסייה אחת או יותר כדי לבצע אינטראקציה ברשת, לנפות באגים ב-JavaScript, לשנות את ה-DOM וה-CSS ועוד. השתמשו במאפיין Debuggee
tabId
כדי לטרגט כרטיסיות עם sendCommand
ולנתב אירועים עד tabId
מתוך onEvent
קריאות חוזרות (callback).
הרשאות
debugger
כדי להשתמש ב-API הזה, עליך להצהיר על ההרשאה "debugger"
במניפסט של התוסף.
{
"name": "My extension",
...
"permissions": [
"debugger",
],
...
}
מושגים ושימוש
אחרי שמצרפים את ה-API chrome.debugger
, אפשר לשלוח פקודות Chrome DevTools Protocol (CDP) ליעד נתון. במסמכי התיעוד האלה אי אפשר לספק הסבר מפורט על ה-CDP. למידע נוסף על CDP, ניתן לעיין במסמכים הרשמיים של CDP.
יעדים
היעדים מייצגים משהו שנמצא בניפוי באגים, למשל כרטיסייה, iframe או worker. כל יעד מזוהה באמצעות UUID ויש לו סוג שמשויך אליו (כמו iframe
, shared_worker
ועוד).
ביעד יכול להיות כמה הקשרים של הפעלה. לדוגמה, iframes בתהליך לא מקבלים יעד ייחודי, אלא מיוצגים כהקשרים שונים שאפשר לגשת אליהם מיעד אחד.
דומיינים מוגבלים
מטעמי אבטחה, ה-API chrome.debugger
לא מאפשר גישה לכל הדומיינים של הפרוטוקולים של כלי הפיתוח ל-Chrome. הדומיינים הזמינים הם: Accessibility, DOMDebugger, CacheStorage, Console, CSS, Database, Debugger, DOM, DOMDebugger, DOMSnapshot, DOMSnapshot, WebAudioWebAuthn
עבודה עם מסגרות
אין מיפוי אחד או אחד של פריימים ליעדים. בכרטיסייה אחת, לכמה מסגרות תהליך עשויות להיות אותו יעד, אבל נעשה בהן שימוש בהקשר הפעלה שונה. מצד שני, יכול להיות שייווצר יעד חדש ל-iframe מחוץ לתהליך.
כדי לצרף לכל המסגרות, עליך לטפל בכל סוג של מסגרת בנפרד:
מאזינים לאירוע
Runtime.executionContextCreated
כדי לזהות הקשרים של ביצוע חדשים שמשויכים לאותן מסגרות תהליך.פועלים לפי השלבים לצירוף ליעדים קשורים כדי לזהות פריימים מחוץ לתהליך.
צירוף ליעדים קשורים
אחרי שמתחברים ליעד, כדאי להתחבר ליעדים קשורים נוספים, כולל מסגרות צאצא שאינן בתהליך עיבוד או עובדים משויכים.
החל מגרסה 125 של Chrome, ה-API של chrome.debugger
תומך בסשנים שטוחים. כך תוכלו להוסיף עוד יעדים בתור ילדים לסשן הראשי של ניפוי הבאגים, ולשלוח להם הודעות בלי צורך בקריאה נוספת אל chrome.debugger.attach
. במקום זאת, אפשר להוסיף את המאפיין sessionId
כשמפעילים את chrome.debugger.sendCommand
כדי לזהות את יעד הצאצא שאליו רוצים לשלוח פקודה.
כדי לצרף באופן אוטומטי מסגרות צאצא מחוץ לתהליך, קודם צריך להוסיף האזנה לאירוע Target.attachedToTarget
:
chrome.debugger.onEvent.addListener((source, method, params) => {
if (method === "Target.attachedToTarget") {
// `source` identifies the parent session, but we need to construct a new
// identifier for the child session
const session = { ...source, sessionId: params.sessionId };
// Call any needed CDP commands for the child session
await chrome.debugger.sendCommand(session, "Runtime.enable");
}
});
לאחר מכן, מפעילים את הצירוף האוטומטי על ידי שליחת הפקודה Target.setAutoAttach
כאשר האפשרות flatten
מוגדרת ל-true
:
await chrome.debugger.sendCommand({ tabId }, "Target.setAutoAttach", {
autoAttach: true,
waitForDebuggerOnStart: false,
flatten: true,
filter: [{ type: "iframe", exclude: false }]
});
דוגמאות
כדי לנסות את ה-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
הסיבה לסיום החיבור.
טיפוסים בני מנייה (enum)
"target_closed"
"canceled_by_user"
TargetInfo
מידע על יעד ניפוי הבאגים
תכונות
-
מחובר
boolean
True אם הכלי לניפוי באגים כבר מצורף.
-
extensionId
מחרוזת אופציונלי
מזהה התוסף, מוגדר אם הסוג = 'background_page'.
-
faviconUrl
מחרוזת אופציונלי
כתובת ה-URL של סמל האתר ביעד.
-
id
string
מזהה יעד.
-
tabId
מספר אופציונלי
מזהה הכרטיסייה, המוגדר אם הסוג == 'page'.
-
title
string
כותרת דף היעד.
-
סוג
סוג היעד.
-
כתובת אתר
string
כתובת ה-URL של היעד.
TargetInfoType
סוג היעד.
טיפוסים בני מנייה (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 התואמים ליעדים הזמינים לניפוי באגים.
-
החזרות
-
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 בכרטיסייה המצורפת.
פרמטרים
-
קריאה חוזרת (callback)
פונקציה
הפרמטר
callback
נראה כך:(source: Debuggee, reason: DetachReason) => void
-
source
-
סיבה
-
onEvent
chrome.debugger.onEvent.addListener(
callback: function,
)
מופעל בכל פעם שניפוי באגים ביעד בעיה באירוע אינסטרומנטציה.
פרמטרים
-
קריאה חוזרת (callback)
פונקציה
הפרמטר
callback
נראה כך:(source: DebuggerSession, method: string, params?: object) => void
-
source
-
method
string
-
params
אובייקט אופציונלי
-