browser.devtools.inspectedWindow

תיאור

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

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

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

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

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

מניפסט

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

"devtools_page"

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

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

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

  • השיטה eval לא משתמשת בעולם מבודד לקוד שנבדק, כך שהקוד יכול לגשת למצב ה-JavaScript של החלון שנבדק. השתמשו בשיטה הזו כשנדרשת גישה למצב ה-JavaScript של הדף שנבדק.
  • הקשר הביצוע של הקוד שמוערך כולל את ה-API של מסוף הכלים למפתחים. לדוגמה, הקוד יכול להשתמש ב-inspect וב-$0.
  • הקוד שנבדק עשוי להחזיר ערך שמועבר לקריאה החוזרת (callback) של התוסף. הערך שמוחזר צריך להיות אובייקט JSON תקין (הוא יכול להכיל רק סוגים פרימיטיביים של JavaScript והפניות א-מחזוריות לאובייקטים אחרים של JSON). חשוב לנקוט משנה זהירות בזמן עיבוד הנתונים שמתקבלים מהדף שנבדק – הקשר הביצוע נשלט בעיקר על ידי הדף שנבדק, ודף זדוני עלול להשפיע על הנתונים שמוחזרים לתוסף.

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

כברירת מחדל, השיטה eval פועלת בהקשר של המסגרת הראשית של הדף שנבדק.

ה-method‏ eval מקבלת ארגומנט שני אופציונלי שבו אפשר להשתמש כדי לציין את ההקשר שבו הקוד מוערך. האובייקט options יכול להכיל אחד או יותר מהמפתחות הבאים:

frameURL
משמש לציון מסגרת שאינה המסגרת הראשית של הדף שנבדק.
contextSecurityOrigin
משמש לבחירת הקשר בתוך המסגרת שצוינה בהתאם למקור באינטרנט.
useContentScriptContext
אם הערך הוא True, הסקריפט יופעל באותו הקשר כמו הסקריפטים של התוכן בתוסף. (שווה ערך לציון המקור באינטרנט של התוסף עצמו כמקור האבטחה של ההקשר). אפשר להשתמש בזה כדי להחליף נתונים עם סקריפט התוכן.

דוגמאות

הקוד הבא בודק את גרסת ה-jQuery שבה נעשה שימוש בדף שנבדק:

browser.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

    מחרוזת

    כתובת ה-URL של המשאב.

  • getContent

    void

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

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

    () => {...}

    • החזרות

      Promise<object>

      ‫Chrome 151 ואילך ‫‎browser.* ‎ מגרסה Chrome 152

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

  • setContent

    void

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

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

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

    • תוכן

      מחרוזת

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

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

      בוליאני

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

    • החזרות

      Promise<object>

      ‫Chrome 151 ואילך ‫‎browser.* ‎ מגרסה Chrome 152

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

מאפיינים

tabId

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

סוג

number

Methods

eval()

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

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

פרמטרים

  • ביטוי

    מחרוזת

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

  • אפשרויות

    object optional

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

    • frameURL

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

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

    • scriptExecutionContext

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

      Chrome 107 ואילך browser.* ‎ מ-Chrome 152 ואילך

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

    • useContentScriptContext

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

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

החזרות

  • Promise<object>

    ‫Chrome 151 ואילך ‫‎browser.* ‎ מגרסה Chrome 152

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

getResources()

browser.devtools.inspectedWindow.getResources(): Promise<Resource[]>

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

החזרות

  • Promise<Resource[]>

    ‫Chrome 151 ואילך ‫‎browser.* ‎ מגרסה Chrome 152

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

reload()

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

טוען מחדש את הדף שנבדק.

פרמטרים

  • reloadOptions

    object optional

    • ignoreCache

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

      כשהערך הוא True, תוכנת הטעינה תעקוף את המטמון לכל משאבי הדף שנבדקו ונטענו לפני שהאירוע load הופעל. ההשפעה דומה ללחיצה על Ctrl+Shift+R בחלון שנבדק או בחלון של הכלים למפתחים.

    • injectedScript

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

      אם צוין, הסקריפט יוחדר לכל מסגרת של הדף שנבדק מיד עם הטעינה, לפני כל אחד מהסקריפטים של המסגרת. הסקריפט לא יופעל אחרי טעינות חוזרות – לדוגמה, אם המשתמש לוחץ על Ctrl+R.

    • userAgent

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

      אם מציינים מחרוזת, היא תחליף את הערך של כותרת ה-HTTP‏ User-Agent שנשלחת בזמן הטעינה של המשאבים בדף שנבדק. המחרוזת גם תעקוף את הערך של המאפיין navigator.userAgent שמוחזר לכל הסקריפטים שפועלים בדף שנבדק.

אירועים

onResourceAdded

browser.devtools.inspectedWindow.onResourceAdded.addListener(
  callback: function,
)

מופעל כשמשאב חדש נוסף לדף שנבדק.

פרמטרים

  • callback

    פונקציה

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

    (resource: Resource) => void

onResourceContentCommitted

browser.devtools.inspectedWindow.onResourceContentCommitted.addListener(
  callback: function,
)

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

פרמטרים

  • callback

    פונקציה

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

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

    • משאב

      משאב

    • תוכן

      מחרוזת