chrome.devtools.inspectedWindow

תיאור

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

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

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

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

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

מניפסט

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

"devtools_page"

הפעלת הקוד בחלון שנבדק

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

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

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

זהירות: עקב שיקולי האבטחה שהוסברו למעלה, השיטה scripting.executeScript היא הדרך המועדפת לאפשר לתוסף לגשת לנתוני DOM של הדף שנבדק במקרים שבהם אין צורך בגישה למצב JavaScript בדף שנבדק.

לתשומת ליבכם, דף יכול לכלול כמה הקשרים שונים של ביצוע 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,
)

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

פרמטרים

• קריאה חוזרת (callback)

  פונקציה

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

  (resources: Resource[])=>void

  • משאבים

    משאב[]

    המשאבים שמופיעים בדף.

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,
)

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

פרמטרים

• קריאה חוזרת (callback)

  פונקציה

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

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

  • מקור מידע

    משאב

  • רווחי

    מחרוזת