תיאור
כדי לבצע פעולות בחלון שנבדק, משתמשים ב-API של chrome.devtools.inspectedWindow
: משיגים את מזהה הכרטיסייה של הדף שנבדק, מעריכים את הקוד בהקשר של החלון שנבדק, טעינה מחדש של הדף או השגת רשימת המשאבים שבדף.
מניפסט
כדי לבצע פעולות בחלון שנבדק, משתמשים ב-chrome.devtools.inspectedWindow
: להשיג את מזהה הכרטיסייה של הדף שנבדק, להעריך את הקוד בהקשר של החלון שנבדק, לטעון מחדש את הדף או להשיג את רשימת המשאבים שבדף.
אפשר לעיין בסיכום של ממשקי ה-API למפתחים כדי לקבל מבוא כללי לשימוש בממשקי ה-API של כלים למפתחים.
סקירה כללית
הנכס tabId
מספק את מזהה הכרטיסייה שאפשר להשתמש בו עם קריאות ל-API של chrome.tabs.*
. עם זאת, שימו לב ש-chrome.tabs.*
API לא חשוף לדפי התוספים של הכלים למפתחים בגלל שיקולי אבטחה – צריך להעביר את מזהה הכרטיסייה לדף הרקע ולהפעיל את פונקציות ה-API של chrome.tabs.*
משם.
ניתן להשתמש בשיטה reload
כדי לטעון מחדש את הדף שנבדק. בנוסף, מבצע הקריאה החוזרת יכול להגדיר שינוי מברירת המחדל למחרוזת של סוכן המשתמש, סקריפט שיתווסף בשלב מוקדם במהלך טעינת הדף או אפשרות לאלץ טעינה מחדש של משאבים שנשמרו במטמון.
משתמשים בקריאה getResources
ובאירוע onResourceContent
כדי להציג את רשימת המשאבים (מסמכים, גיליונות סגנונות, סקריפטים, תמונות וכו') בדף שנבדק. יכול להיות שהשיטות getContent
ו-setContent
של המחלקה Resource
יחד עם האירוע onResourceContentCommitted
ישמשו כדי לתמוך בשינוי של תוכן המשאב, לדוגמה, על ידי עורך חיצוני.
הפעלת קוד בחלון שנבדק
השיטה eval
מאפשרת לתוספים להפעיל קוד JavaScript בהקשר של הדף שנבדק. השיטה הזו עוצמתית כשמשתמשים בה בהקשר הנכון, ומסוכנת כשמשתמשים בה באופן בלתי הולם. השתמשו בשיטה tabs.executeScript
, אלא אם אתם צריכים את הפונקציונליות הספציפית שהשיטה eval
מספקת.
אלה ההבדלים העיקריים בין השיטה eval
לבין השיטה tabs.executeScript
:
- בשיטה
eval
לא נעשה שימוש בעולם מבודד לקוד שנבדק, ולכן מצב ה-JavaScript של החלון שנבדק נגיש לקוד. השתמשו בשיטה הזו כשנדרשת גישה למצב JavaScript של הדף שנבדק. - הקשר הביצוע של הקוד שנבדק כולל את ה-API של מסוף הכלים למפתחים.
לדוגמה, הקוד יכול להשתמש ב-
inspect
וב-$0
. - הקוד שהוערך עשוי להחזיר ערך שמועבר אל הקריאה החוזרת של התוסף. הערך שמוחזר צריך להיות אובייקט JSON חוקי (הוא יכול להכיל רק סוגי JavaScript פרימיטיביים והפניות מחזוריות לאובייקטים אחרים של JSON). שימו לב להיזהר במהלך עיבוד הנתונים שהתקבלו מהדף שנבדק – הקשר הביצוע נשלט בעיקר על ידי הדף שנבדק. דף זדוני עלול להשפיע על הנתונים שמוחזרים לתוסף.
לתשומת ליבכם, דף יכול לכלול כמה הקשרים שונים של ביצוע JavaScript. לכל מסגרת יש הקשר משלה, וגם הקשר נוסף לכל תוסף שיש בו סקריפטים של תוכן שפועלים במסגרת הזו.
כברירת מחדל, השיטה eval
מופעלת בהקשר של המסגרת הראשית של הדף שנבדק.
השיטה eval
משתמשת בארגומנט שני אופציונלי, שניתן להשתמש בו כדי לציין את ההקשר שבו הקוד ייבדק. האובייקט options יכול להכיל אחד או יותר מהמפתחות הבאים:
frameURL
- משמש לציון מסגרת שאינה המסגרת הראשית של הדף שנבדק.
contextSecurityOrigin
- משמשת לבחירת הקשר בתוך המסגרת שצוינה בהתאם למקור האינטרנט שלו.
useContentScriptContext
- אם הערך הוא true, צריך להפעיל את הסקריפט באותו הקשר שבו פועלים הסקריפטים של התוכן של התוספים. (שווה ערך להגדרת ארגון האינטרנט של התוספים כמקור אבטחת ההקשר). אפשר להשתמש בו כדי להחליף נתונים בסקריפט התוכן.
דוגמאות
הקוד הבא מחפש את גרסת jQuery שבה נעשה שימוש בדף שנבדק:
chrome.devtools.inspectedWindow.eval(
"jQuery.fn.jquery",
function(result, isException) {
if (isException) {
console.log("the page is not using jQuery");
} else {
console.log("The page is using jQuery v" + result);
}
}
);
כדי לנסות את ה-API הזה, צריך להתקין את דוגמאות ל-API של devtools מהמאגר chrome-extension-samples.
סוגים
Resource
משאב בדף שנבדק, כמו מסמך, סקריפט או תמונה.
תכונות
-
כתובת אתר
מחרוזת
כתובת ה-URL של המשאב.
-
getContent
void
הפונקציה מקבלת את התוכן של המשאב.
הפונקציה
getContent
נראית כך:(callback: function) => {...}
-
קריאה חוזרת (callback)
פונקציה
הפרמטר
callback
נראה כך:(content: string, encoding: string) => void
-
רווחי
מחרוזת
תוכן המשאב (שיכול להיות מקודד).
-
קידוד
מחרוזת
אם התוכן לא מקודד, השם ריק אם הוא לא מקודד. נכון לעכשיו, יש תמיכה רק ב-base64.
-
-
-
setContent
void
מגדיר את התוכן של המשאב.
הפונקציה
setContent
נראית כך:(content: string, commit: boolean, callback?: function) => {...}
-
רווחי
מחרוזת
תוכן חדש של המשאב. כרגע יש תמיכה רק במשאבים מסוג הטקסט.
-
להוריד לביצוע (Commit)
boolean
True אם המשתמש סיים לערוך את המשאב והתוכן החדש של המשאב יישאר ללא שינוי. FALSE אם זהו שינוי קל שנשלח בזמן שהמשתמש עורך את המשאב.
-
קריאה חוזרת (callback)
פונקציה אופציונלי
הפרמטר
callback
נראה כך:(error?: object) => void
-
error
אובייקט אופציונלי
מוגדר לערך 'לא מוגדר' אם תוכן המשאב הוגדר בהצלחה. אחרת, השגיאה מתארת את השגיאה.
-
-
תכונות
tabId
המזהה של הכרטיסייה שנבדקה. ניתן להשתמש במזהה הזה עם chrome.tabs.* API.
סוג
מספר
שיטות
eval()
chrome.devtools.inspectedWindow.eval(
expression: string,
options?: object,
callback?: function,
)
מבצעת הערכה של ביטוי JavaScript בהקשר של המסגרת הראשית של הדף שנבדק. הביטוי צריך להעריך לאובייקט תואם JSON, אחרת המערכת עלולה לגרום לחריגה. פונקציית ההערכה יכולה לדווח על שגיאה בצד של כלי הפיתוח או על חריגת JavaScript שמתרחשת במהלך ההערכה. בכל מקרה, הפרמטר result
של הקריאה החוזרת הוא undefined
. במקרה של שגיאה בצד של כלי הפיתוח, הפרמטר isException
הוא לא null, והערך isError
מוגדר כ-true ו-code
מוגדר כקוד שגיאה. במקרה של שגיאת JavaScript, isException
מוגדר כ-true ו-value
מוגדר לערך המחרוזת של אובייקט שנזרק.
פרמטרים
-
ביטוי
מחרוזת
ביטוי להערכה.
-
אפשרויות
אובייקט אופציונלי
פרמטר האפשרויות יכול להכיל אפשרות אחת או יותר.
-
frameURL
מחרוזת אופציונלי
אם צוין אחרת, הביטוי ייבדק ב-iframe שכתובת ה-URL שלו תואמת לזו שצוינה. כברירת מחדל, הביטוי מוערך במסגרת העליונה של הדף שנבדק.
-
scriptExecutionContext
מחרוזת אופציונלי
Chrome 107 ומעלהמעריכים את הביטוי בהקשר של סקריפט תוכן של תוסף שתואם למקור שצוין. אם קיימת אפשרות, ScriptExecutionContext מבטל את ההגדרה 'true' ב-useContentScriptContext.
-
useContentScriptContext
בוליאני אופציונלי
מעריכים את הביטוי בהקשר של סקריפט התוכן של תוסף הקריאה, בתנאי שסקריפט התוכן כבר מוחדר לדף שנבדק. אחרת, הביטוי לא ייבדק והקריאה החוזרת תופעל כשפרמטר החריגה יוגדר לאובייקט שבו השדה
isError
מוגדר כ-true והשדהcode
מוגדר ל-E_NOTFOUND
.
-
-
קריאה חוזרת (callback)
פונקציה אופציונלי
הפרמטר
callback
נראה כך:(result: object, exceptionInfo: object) => void
-
תוצאה אחת
אובייקט
תוצאת ההערכה.
-
exceptionInfo
אובייקט
אובייקט שמספק פרטים אם התרחשה חריגה במהלך הערכת הביטוי.
-
קוד
מחרוזת
מגדירים אם השגיאה אירעה בצד של כלי הפיתוח לפני הערכת הביטוי.
-
תיאור
מחרוזת
מגדירים אם השגיאה אירעה בצד של כלי הפיתוח לפני הערכת הביטוי.
-
פרטים
כל[]
ההגדרה קובעת אם השגיאה אירעה בצד של כלי הפיתוח לפני שהביטוי עבר הערכה, מכיל את מערך הערכים שניתן להחליף במחרוזת התיאור כדי לספק מידע נוסף על הגורם לשגיאה.
-
isError
boolean
מגדירים אם השגיאה אירעה בצד של כלי הפיתוח לפני הערכת הביטוי.
-
isException
boolean
מגדירים אם הקוד המוערך יוצר חריג לא מטופל.
-
value
מחרוזת
מגדירים אם הקוד המוערך יוצר חריג לא מטופל.
-
-
getResources()
chrome.devtools.inspectedWindow.getResources(
callback: function,
)
מאחזרת את רשימת המשאבים מהדף שנבדק.
פרמטרים
reload()
chrome.devtools.inspectedWindow.reload(
reloadOptions?: object,
)
טוען מחדש את הדף שנבדק.
פרמטרים
-
reloadOptions
אובייקט אופציונלי
-
ignoreCache
בוליאני אופציונלי
כאשר הערך הוא True, הטוען יעקוף את המטמון לכל משאבי הדף שנבדקו שנטענים לפני שהאירוע
load
יופעל. הפעולה דומה ללחיצה על Ctrl+Shift+R בחלון שנבדק או בחלון 'כלים למפתחים'. -
injectedScript
מחרוזת אופציונלי
אם צוין, הסקריפט יוכנס לכל מסגרת של הדף שנבדק מיד לאחר הטעינה, לפני סקריפטים של המסגרת. הסקריפט לא יוחדר אחרי טעינות מחדש הבאות. לדוגמה, אם המשתמש מקיש על Ctrl+R.
-
userAgent
מחרוזת אופציונלי
אם היא מוגדרת, המחרוזת תבטל את הערך של כותרת ה-HTTP של
User-Agent
שנשלח במהלך טעינת המשאבים של הדף שנבדק. המחרוזת גם תבטל את הערך של המאפייןnavigator.userAgent
שמוחזר לסקריפטים שפועלים בדף שנבדק.
-
אירועים
onResourceAdded
chrome.devtools.inspectedWindow.onResourceAdded.addListener(
callback: function,
)
מופעל כשנוסף משאב חדש לדף שנבדק.
פרמטרים
-
קריאה חוזרת (callback)
פונקציה
הפרמטר
callback
נראה כך:(resource: Resource) => void
-
מקור מידע
-
onResourceContentCommitted
chrome.devtools.inspectedWindow.onResourceContentCommitted.addListener(
callback: function,
)
מופעל כשמתבצעת התחייבות לגרסה חדשה של המשאב (למשל, משתמש שומר גרסה ערוכה של המשאב בכלים למפתחים).