chrome.devtools.inspectedWindow

refresh date: 2026-09-25 robots: noindex

תיאור

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

מניפסט

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

"devtools_page"

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

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

סקירה כללית

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

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

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

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

ה-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 שבה נעשה שימוש בדף שנבדק:

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

    מחרוזת

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

  • getContent

    void

    Promise

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

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

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

    • callback

      function optional

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

      (response: object) => void

      • תשובה

        אובייקט

        ‫Chrome מגרסה 151 ואילך

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

        • תוכן

          מחרוזת

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

        • קידוד

          מחרוזת

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

    • החזרות

      Promise<object>

      ‫Chrome מגרסה 151 ואילך

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

      הבטחות נתמכות רק ב-Manifest V3 ואילך, בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callbacks).

  • setContent

    void

    Promise

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

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

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

    • תוכן

      מחרוזת

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

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

      בוליאני

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

    • callback

      function optional

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

      (error?: object) => void

      • error

        object optional

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

    • החזרות

      Promise<object>

      ‫Chrome מגרסה 151 ואילך

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

      הבטחות נתמכות רק ב-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 יכולה לדווח על שגיאה בצד של כלי הפיתוח או על חריגה ב-JavaScript שמתרחשת במהלך ההערכה. בשני המקרים, הפרמטר result של הקריאה החוזרת הוא undefined. במקרה של שגיאה בצד של כלי הפיתוח, הפרמטר isException הוא לא null, הערך של isError מוגדר כ-true והערך של code מוגדר כקוד שגיאה. במקרה של שגיאת JavaScript, הערך של isException מוגדר כ-true והערך של value מוגדר כערך המחרוזת של האובייקט שנזרק.

פרמטרים

  • ביטוי

    מחרוזת

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

  • אפשרויות

    object optional

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

    • frameURL

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

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

    • scriptExecutionContext

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

      ‫Chrome מגרסה 107 ואילך

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

    • useContentScriptContext

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

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

  • callback

    function optional

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

    (response: object) => void

    • תשובה

      אובייקט

      ‫Chrome מגרסה 151 ואילך

      תוצאת ההערכה ומידע על החריגה.

      • exceptionInfo

        אובייקט

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

        • קוד

          מחרוזת

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

        • תיאור

          מחרוזת

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

        • פרטים

          any[]‎

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

        • isError

          בוליאני

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

        • isException

          בוליאני

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

        • ערך

          מחרוזת

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

      • תוצאה

        אובייקט

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

החזרות

  • Promise<object>

    ‫Chrome מגרסה 151 ואילך

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

    הבטחות נתמכות רק ב-Manifest V3 ואילך, בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callbacks).

getResources()

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

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

פרמטרים

  • callback

    function optional

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

    (resources: Resource[]) => void

    • משאבים

      משאב[]

      המשאבים שבדף.

החזרות

  • Promise<Resource[]>

    ‫Chrome מגרסה 151 ואילך

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

    הבטחות נתמכות רק ב-Manifest V3 ואילך, בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callbacks).

reload()

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

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

    • משאב

      משאב

    • תוכן

      מחרוזת