chrome.devtools.inspectedWindow

תיאור

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

מניפסט

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

"devtools_page"

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

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

סקירה כללית

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

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

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

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

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

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

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

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

כברירת מחדל, ה-method 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 הזה, צריך להתקין את הדוגמאות של ממשקי devtools API מ-chrome-extension-samples. של מאגר הנתונים.

סוגים

Resource

משאב בדף שנבדק, כמו מסמך, סקריפט או תמונה.

מאפיינים

  • כתובת אתר

    מחרוזת

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

  • getContent

    ריק

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

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

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

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

      פונקציה

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

      (content: string, encoding: string) => void

      • תוכן

        מחרוזת

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

      • קידוד

        מחרוזת

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

  • setContent

    ריק

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

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

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

    • תוכן

      מחרוזת

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

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

      בוליאני

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

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

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

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

      (error?: object) => void

      • error

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

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

מאפיינים

tabId

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

סוג

number

שיטות

eval()

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

בוחנת ביטוי JavaScript בהקשר של המסגרת הראשית של הדף הנבדק. הערך של הביטוי צריך להיות אובייקט שתואם ל-JSON, אחרת המערכת תחריג חריג. פונקציית eval יכולה לדווח על שגיאה בצד של כלי הפיתוח או על חריג של 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

        בוליאני

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

      • isException

        בוליאני

        מגדירים אם הקוד שנבדק מייצר חריג לא מטופל.

      • ערך

        מחרוזת

        מגדירים אם הקוד שנבדק מייצר חריג לא מטופל.

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

    • משאב

      משאב

    • תוכן

      מחרוזת