תיאור
ה-API של chrome.debugger
משמש כהעברה חלופית של הפרוטוקול לניפוי באגים מרחוק של Chrome. אפשר להשתמש ב-chrome.debugger
כדי לצרף כרטיסייה אחת או יותר כדי לסייע באינטראקציה ברשת, לנפות באגים ב-JavaScript, לשנות את ה-DOM וה-CSS ועוד. אפשר להשתמש בנכס Debuggee
tabId
כדי לטרגט כרטיסיות עם sendCommand
ולנתב אירועים לפי tabId
מקריאות חוזרות (callback) של onEvent
.
הרשאות
debugger
כדי להשתמש ב-API הזה, צריך להצהיר על ההרשאה "debugger"
במניפסט של התוסף.
{
"name": "My extension",
...
"permissions": [
"debugger",
],
...
}
מושגים ושימוש
לאחר ההוספה, ה-API של chrome.debugger
יאפשר לך לשלוח את פרוטוקול כלי הפיתוח ל-Chrome
פקודות (CDP) ליעד נתון. אין הסבר מעמיק על CDP
לקבלת מידע נוסף על CDP, אפשר לעיין
מסמכי התיעוד הרשמיים של CDP.
יעדים
היעדים מייצגים משהו שמתבצע בו ניפוי באגים, למשל כרטיסייה,
iframe או worker. כל יעד מזוהה באמצעות UUID ויש לו
סוג (למשל iframe
, shared_worker
ועוד).
בתוך יעד, יכולים להיות כמה הקשרים של הפעלה – לדוגמה, iframes תהליך לא מקבלים יעד ייחודי אלא מיוצגים הקשרים שונים שניתן לגשת אליהם מיעד יחיד.
דומיינים מוגבלים
מטעמי אבטחה, ה-API של chrome.debugger
לא מספק גישה לכל כלי הפיתוח ל-Chrome
דומיינים של פרוטוקול. הדומיינים הזמינים הם: נגישות,
ביקורות, CacheStorage, Console,
CSS, מסד נתונים, כלי לניפוי באגים, DOM,
DOMDebugger, DOMSnapshot,
אמולציה, אחזור, IO, קלט,
מפקח, יומן, רשת, שכבת על,
דף, ביצועים, Profiler,
זמן ריצה, אחסון, יעד, מעקב,
WebAudio ו-WebAuthn.
עבודה עם מסגרות
אין מיפוי אחד או אחד של פריימים ליעדים. בכרטיסייה יחידה, עשויות להיות כמה מסגרות תהליך זהות עם אותו יעד, אבל נעשה בהן שימוש הקשר לביצוע. מצד שני, יעד חדש עשוי להיות נוצרה ל-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
מידע על היעד של ניפוי באגים
מאפיינים
-
מצורף
בוליאני
הערך הוא True אם הכלי לניפוי באגים כבר מצורף.
-
extensionId
מחרוזת אופציונלי
מזהה התוסף, שמוגדר אם הסוג הוא = 'background_page'.
-
faviconUrl
מחרוזת אופציונלי
כתובת ה-URL של סמל האתר בקמפיין.
-
id [מזהה]
מחרוזת
מזהה היעד.
-
tabId
מספר אופציונלי
מזהה הכרטיסייה, המוגדר אם הסוג == 'page'.
-
title
מחרוזת
כותרת דף היעד.
-
סוג
סוג היעד.
-
כתובת אתר
מחרוזת
כתובת ה-URL של היעד.
TargetInfoType
סוג היעד.
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 שתואמים ליעדי ניפוי הבאגים הזמינים.
-
החזרות
-
Promise<TargetInfo[]>
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<object | לא מוגדר>
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
מחרוזת
-
פרמטרים
אובייקט אופציונלי
-