chrome.devtools.inspectedWindow

תיאור

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

מניפסט

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

"devtools_page"

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

במאמר סיכום של ממשקי DevTools API יש מבוא כללי לשימוש בממשקי Developer Tools API.

סקירה כללית

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

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

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

הרצת קוד בחלון שנבדק

השיטה 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

    Promise

    מקבל את התוכן של המשאב.

    הפונקציה getContent נראית כך: 

    (callback?: function) => {...}

    • callback

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

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

      (response: object) => void

      • תשובה

        אובייקט

        בהמתנה

        אובייקט שמכיל את תוכן המשאב והקידוד שלו.

        • תוכן

          מחרוזת

          התוכן של המשאב (יכול להיות שהוא מקודד).

        • קידוד

          מחרוזת

          השדה ריק אם התוכן לא מקודד, אחרת מופיע בו שם הקידוד. בשלב הזה יש תמיכה רק ב-base64.

    • החזרות

      Promise<object>

      בהמתנה

      פונקציה שמקבלת תוכן של משאבים כשהבקשה מסתיימת.

      התמיכה ב-Promises קיימת רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.

  • setContent

    void

    Promise

    מגדיר את התוכן של המשאב.

    הפונקציה setContent נראית כך: 

    (content: string, commit: boolean, callback?: function) => {...}

    • תוכן

      מחרוזת

      תוכן חדש של מקור המידע. בשלב הזה יש תמיכה רק במשאבים עם סוג הטקסט.

    • להוריד לביצוע (Commit)

      בוליאני

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

    • callback

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

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

      (error?: object) => void

      • error

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

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

    • החזרות

      Promise<object>

      בהמתנה

      פונקציה שמופעלת עם השלמת הבקשה.

      התמיכה ב-Promises קיימת רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.

מאפיינים

tabId

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

סוג

number

Methods

eval()

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

הכלי מעריך ביטוי 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 נראה כך: 

    (response: object) => void

    • תשובה

      אובייקט

      בהמתנה

      התוצאה של ההערכה ופרטי החריגה.

      • exceptionInfo

        אובייקט

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

        • קוד

          מחרוזת

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

        • תיאור

          מחרוזת

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

        • פרטים

          כל[]

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

        • isError

          בוליאני

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

        • isException

          בוליאני

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

        • ערך

          מחרוזת

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

      • תוצאה

        אובייקט

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

החזרות

  • Promise<object>

    בהמתנה

    פונקציה שמופעלת כשההערכה מסתיימת.

    התמיכה ב-Promises קיימת רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.

getResources()

Promise 
chrome.devtools.inspectedWindow.getResources(
  callback?: function,
): Promise<Resource[]>

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

פרמטרים

  • callback

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

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

    (resources: Resource[]) => void

    • משאבים

      Resource[]

      המשאבים בדף.

החזרות

  • Promise<Resource[]>

    בהמתנה

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

    התמיכה ב-Promises קיימת רק ב-Manifest V3 ואילך. בפלטפורמות אחרות צריך להשתמש ב-callbacks.

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

    • משאב

      משאב

    • תוכן

      מחרוזת