chrome.devtools.inspectedWindow

תיאור

אפשר להשתמש ב-chrome.devtools.inspectedWindow API כדי ליצור אינטראקציה עם החלון שנבדק: לקבל את מזהה הכרטיסייה של הדף שנבדק, להעריך את הקוד בהקשר של החלון שנבדק, לטעון מחדש את הדף או לקבל את רשימת המשאבים בדף.

במאמר סיכום של ממשקי DevTools API יש מבוא כללי לשימוש בממשקי API של כלים למפתחים.

המאפיין tabId מספק את מזהה הכרטיסייה שבו אפשר להשתמש בקריאות ל-API של chrome.tabs.*. עם זאת, חשוב לשים לב ש-chrome.tabs.* API לא נחשף לדפי התוסף של כלי הפיתוח משיקולי אבטחה – תצטרכו להעביר את מזהה הכרטיסייה לדף הרקע ולהפעיל משם את הפונקציות של chrome.tabs.* API.

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

משתמשים בקריאה getResources ובאירוע onResourceContent כדי לקבל את רשימת המשאבים (מסמכים, גיליונות סגנונות, סקריפטים, תמונות וכו') בדף שנבדק. אפשר להשתמש בשיטות getContent ו-setContent של המחלקה Resource יחד עם האירוע onResourceContentCommitted כדי לתמוך בשינוי של תוכן המשאב, למשל על ידי עורך חיצוני.

מניפסט

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

"devtools_page"

הרצת קוד בחלון הבדיקה

השיטה eval מאפשרת לתוספים להריץ קוד JavaScript בהקשר של הדף שנבדק. השיטה הזו יעילה מאוד כשמשתמשים בה בהקשר הנכון, ומסוכנת כשמשתמשים בה בצורה לא הולמת. מומלץ להשתמש בשיטה tabs.executeScript, אלא אם אתם צריכים את הפונקציונליות הספציפית ששיטת eval מספקת.

אלה ההבדלים העיקריים בין השיטות eval ו-tabs.executeScript:

  • השיטה eval לא משתמשת בסביבה מבודדת לקוד שנבדק, ולכן הקוד יכול לגשת למצב JavaScript של החלון שנבדק. כדאי להשתמש בשיטה הזו כשנדרשת גישה למצב JavaScript של הדף שנבדק.
  • הקשר הביצועי של הקוד שנבדק כולל את Developer Tools console 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 של כלי הפיתוח ממאגר 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)

      בוליאני

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

    • callback

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

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

      (error?: object) => void

      • error

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

        הערך הוא undefined אם תוכן המשאב הוגדר בהצלחה, אחרת מתואר כאן סוג השגיאה.

מאפיינים

tabId

המזהה של הכרטיסייה שנבדקת. יכול להיות שייעשה שימוש במזהה הזה עם chrome.tabs.* API.

סוג

number

Methods

eval()

chrome.devtools.inspectedWindow.eval(
  expression: string,
  options?: object,
  callback?: function,
): void

הכלי מעריך ביטוי JavaScript בהקשר של המסגרת הראשית של הדף שנבדק. הביטוי חייב להניב אובייקט תואם JSON, אחרת מוצג חריג. הפונקציה eval יכולה לדווח על שגיאה בצד DevTools או על חריגה ב-JavaScript שמתרחשת במהלך ההערכה. בכל מקרה, הפרמטר result של הקריאה החוזרת (callback) הוא undefined. במקרה של שגיאה בצד כלי הפיתוח, הפרמטר isException לא ריק, הערך של isError הוא true והערך של code הוא קוד שגיאה. במקרה של שגיאת JavaScript, הערך של isException מוגדר כ-true והערך של value מוגדר כערך המחרוזת של האובייקט שהושלך.

פרמטרים

  • ביטוי

    מחרוזת

    ביטוי להערכה.

  • options

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

    הפרמטר options יכול להכיל אפשרות אחת או יותר.

    • frameURL

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

      אם מציינים ביטוי, הוא מוערך ב-iframe שכתובת ה-URL שלו תואמת לכתובת ה-URL שצוינה. כברירת מחדל, הביטוי מוערך במסגרת העליונה של הדף שנבדק.

    • scriptExecutionContext

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

      ‫Chrome 107 ואילך

      הערכת הביטוי בהקשר של סקריפט תוכן של תוסף שתואם למקור שצוין. אם מציינים ערך, scriptExecutionContext מבטל את ההגדרה 'true' ב-useContentScriptContext.

    • useContentScriptContext

      boolean אופציונלי

      הערכת הביטוי בהקשר של סקריפט התוכן של התוסף שקורא לפונקציה, בתנאי שסקריפט התוכן כבר הוחדר לדף שנבדק. אם לא, הביטוי לא מוערך והקריאה החוזרת מופעלת עם פרמטר החריגה שמוגדר לאובייקט שבו השדה isError מוגדר ל-true והשדה code מוגדר ל-E_NOTFOUND.

  • callback

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

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

    (result: object, exceptionInfo: object) => void

    • תוצאה

      אובייקט

      תוצאת ההערכה.

    • exceptionInfo

      אובייקט

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

      • קוד

        מחרוזת

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

      • תיאור

        מחרוזת

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

      • פרטים

        כל[]

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

      • isError

        בוליאני

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

      • isException

        בוליאני

        הגדרת האפשרות אם הקוד המוערך יוצר חריגה לא מטופלת.

      • ערך

        מחרוזת

        הגדרת האפשרות אם הקוד המוערך יוצר חריגה לא מטופלת.

getResources()

chrome.devtools.inspectedWindow.getResources(
  callback: function,
): void

אחזור רשימת המשאבים מהדף שנבדק.

פרמטרים

  • callback

    פונקציה

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

    (resources: Resource[]) => void

    • משאבים

      Resource[]

      המשאבים בדף.

reload()

chrome.devtools.inspectedWindow.reload(
  reloadOptions?: object,
): void

טעינה מחדש של הדף שנבדק.

פרמטרים

  • reloadOptions

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

    • ignoreCache

      boolean אופציונלי

      אם הערך הוא 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,
)

האירוע מופעל כשמתבצעת שמירה של עדכון חדש של המשאב (למשל, כשמשתמש שומר גרסה ערוכה של המשאב בכלי הפיתוח).

פרמטרים

  • callback

    פונקציה

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

    (resource: Resource, content: string) => void

    • משאב

      משאב

    • תוכן

      מחרוזת