chrome.devtools.inspectedWindow

refresh date: 2026-09-25 robots: noindex

شرح

از chrome.devtools.inspectedWindow API برای تعامل با پنجره بازرسی‌شده استفاده کنید: شناسه برگه را برای صفحه بازرسی‌شده دریافت کنید، کد را در زمینه پنجره بازرسی‌شده ارزیابی کنید، صفحه را مجدداً بار کنید، یا فهرست منابع درون صفحه را دریافت کنید.

مانیفست

برای استفاده از این میانای برنامه‌سازی کاربردی، کلیدهای زیر باید در مانیفست اعلام شوند.

"devtools_page"

از chrome.devtools.inspectedWindow برای تعامل با پنجره بازرسی‌شده استفاده کنید: شناسه برگه را برای صفحه بازرسی‌شده دریافت کنید، کد را در زمینه پنجره بازرسی‌شده ارزیابی کنید، صفحه را مجدداً بار کنید، یا فهرست منابع درون صفحه را دریافت کنید.

برای آشنایی کلی با نحوه استفاده از میاناهای برنامه‌سازی کاربردی «ابزارهای توسعه‌دهندگان»، به خلاصه میاناهای برنامه‌سازی کاربردی DevTools مراجعه کنید.

نمای کلی

مشخصه tabId شناسه برگه‌ای را ارائه می‌دهد که می‌توانید با فراخوانی‌های میانای برنامه‌سازی کاربردی chrome.tabs.* از آن استفاده کنید. بااین‌حال، لطفاً توجه داشته باشید که به‌دلیل ملاحظات امنیتی، chrome.tabs.* API در صفحه‌های افزونه «ابزارهای توسعه‌دهندگان» نمایش داده نمی‌شود—باید شناسه برگه را به صفحه پس‌زمینه ارسال کنید و توابع chrome.tabs.* API را از آنجا فراخوانی کنید.

ممکن است از روش reload برای بار کردن مجدد صفحه بازرسی‌شده استفاده شود. علاوه‌براین، تماس‌گیرنده می‌تواند یک لغو برای رشته نماینده کاربر، یک اسکریپت که در اوایل بارگیری صفحه تزریق می‌شود، یا یک گزینه برای اجبار به بارگیری مجدد منابع ذخیره‌شده در حافظه پنهان را مشخص کند.

از فراخوانی getResources و رویداد onResourceContent برای دریافت فهرست منابع (اسناد، برگه‌های سبک نگارش، اسکریپت‌ها، تصاویر، و غیره) در صفحه بازرسی‌شده استفاده کنید. روش‌های getContent و setContent کلاس Resource به‌همراه رویداد onResourceContentCommitted ممکن است برای پشتیبانی از اصلاح محتوای منبع، برای مثال توسط ویرایشگر خارجی، استفاده شود.

اجرای کد در پنجره بازرسی‌شده

روش eval به افزونه‌ها امکان می‌دهد کد جاوا اسکریپت را در بافت صفحه بازرسی‌شده اجرا کنند. این روش اگر در بافت مناسب استفاده شود قدرتمند است و اگر به‌طور نامناسب استفاده شود خطرناک است. از روش tabs.executeScript استفاده کنید، مگراینکه به عملکرد خاصی نیاز داشته باشید که روش eval ارائه می‌دهد.

تفاوت‌های اصلی بین روش‌های eval و tabs.executeScript در اینجا آمده است:

  • روش eval از دنیای ایزوله‌شده برای کد درحال ارزیابی استفاده نمی‌کند، بنابراین وضعیت جاوا اسکریپت پنجره بازرسی‌شده برای کد قابل‌دسترسی است. وقتی دسترسی به وضعیت جاوا اسکریپت صفحه بازرسی‌شده لازم است، از این روش استفاده کنید.
  • زمینه اجرای کدی که ارزیابی می‌شود شامل میانای برنامه‌سازی کاربردی کنسول «ابزارهای توسعه‌دهندگان» است. برای مثال، کد می‌تواند از inspect و $0 استفاده کند.
  • کد ارزیابی‌شده ممکن است مقداری را برگرداند که به فراخوانی برگشتی افزونه ارسال می‌شود. مقدار برگردانده‌شده باید شیء JSON معتبر باشد (فقط می‌تواند شامل انواع جاوا اسکریپت اولیه و ارجاع‌های غیرچرخه‌ای به اشیاء JSON دیگر باشد). لطفاً هنگام پردازش داده‌های دریافتی از صفحه بازرسی‌شده، بسیار مراقب باشید—زمینه اجرا اساساً توسط صفحه بازرسی‌شده کنترل می‌شود؛ صفحه مخرب ممکن است بر داده‌هایی که به افزونه برگردانده می‌شود تأثیر بگذارد.

توجه داشته باشید که یک صفحه می‌تواند شامل چندین زمینه اجرای جاوا اسکریپت مختلف باشد. هر قاب بافت خودش را دارد، به‌علاوه یک بافت اضافی برای هر افزونه‌ای که دستورگان محتوا در آن قاب اجرا می‌کند.

به‌طور پیش‌فرض، روش eval در بافت قاب اصلی صفحه بازرسی‌شده اجرا می‌شود.

روش eval یک آرگومان دوم اختیاری می‌گیرد که می‌توانید از آن برای مشخص کردن زمینه‌ای که کد در آن ارزیابی می‌شود استفاده کنید. این شیء options می‌تواند شامل یک یا چند کلید زیر باشد:

frameURL
برای مشخص کردن قابی غیراز قاب اصلی صفحه بازرسی‌شده استفاده کنید.
contextSecurityOrigin
از این گزینه برای انتخاب زمینه‌ای در قاب مشخص‌شده براساس مبدأ وب آن استفاده کنید.
useContentScriptContext
اگر درست باشد، دستورگان را در همان بافتار دستورگان‌های محتوای افزونه اجرا می‌کند. (معادل با مشخص کردن مبدأ وب خود افزونه به‌عنوان مبدأ امنیتی بافت.) از این مورد می‌توان برای تبادل داده با متن محتوا استفاده کرد.

مثال‌ها

کد زیر نسخه 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);
    }
  }
);

برای امتحان کردن این میانای برنامه‌سازی کاربردی، نمونه‌های میانای برنامه‌سازی کاربردی devtools را از مخزن chrome-extension-samples نصب کنید.

انواع

Resource

منبعی در صفحه بازرسی‌شده، مثل سند، اسکریپت، یا تصویر.

مشخصات

  • نشانی وب

    رشته

    نشانی وب منبع.

  • getContent

    باطل کردن

    قول

    محتوای منبع را دریافت می‌کند.

    تابع getContent به‌صورت زیر است: 

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

    • تماس برگشتی

      تابع اختیاری

      پارامتر callback به‌صورت زیر است: 

      (response: object) => void

      • پاسخ

        شیء

        Chrome نسخه ۱۵۱ و بالاتر

        شیئی که حاوی محتوای منبع و کدگذاری آن است.

        • محتوا

          رشته

          محتوای منبع (احتمالاً کدبندی‌شده).

        • کدبندی

          رشته

          اگر محتوا کدگذاری نشده باشد، خالی است، درغیراین‌صورت نام کدگذاری است. درحال‌حاضر، فقط base64 پشتیبانی می‌شود.

    • returns

      Promise<object>

      Chrome نسخه ۱۵۱ و بالاتر

      تابعی که محتوای منبع را پس‌از تکمیل درخواست دریافت می‌کند.

      ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

  • setContent

    باطل کردن

    قول

    محتوای منبع را تنظیم می‌کند.

    تابع setContent به‌صورت زیر است: 

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

    • محتوا

      رشته

      محتوای جدید منبع. درحال‌حاضر فقط منابعی که نوع نوشتار دارند پشتیبانی می‌شوند.

    • انجام دادن

      بولی

      اگر کاربر ویرایش منبع را تمام کرده باشد و محتوای جدید منبع باید حفظ شود، مقدار True است؛ اگر این تغییر جزئی باشد و درحین ویرایش منبع توسط کاربر ارسال شده باشد، مقدار False است.

    • تماس برگشتی

      تابع اختیاری

      پارامتر callback به‌صورت زیر است: 

      (error?: object) => void

      • خطا

        شیء اختیاری

        اگر محتوای منبع با موفقیت تنظیم شده باشد، روی تعریف‌نشده تنظیم می‌شود؛ درغیراین‌صورت، خطا را شرح می‌دهد.

    • returns

      Promise<object>

      Chrome نسخه ۱۵۱ و بالاتر

      تابعی که پس‌از تکمیل درخواست فراخوانی می‌شود.

      ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

مشخصات

tabId

شناسه برگه‌ای که دردست بازرسی است. این شناسه ممکن است با chrome.tabs.* استفاده شود API.

نوع

شماره

روش‌ها

eval()

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

عبارت جاوا اسکریپت را در بافت قاب اصلی صفحه بازرسی‌شده ارزیابی می‌کند. عبارت باید به شیء سازگار با JSON ارزیابی شود، درغیراین‌صورت استثنا ایجاد می‌شود. تابع eval می‌تواند خطای سمت DevTools یا استثنای JavaScript را که درطول ارزیابی رخ می‌دهد گزارش کند. در هر دو حالت، پارامتر result پاسخ تماس undefined است. درصورت بروز خطا در سمت DevTools، پارامتر isException غیرتهی است و isError روی true و code روی کد خطا تنظیم شده است. درصورت بروز خطای جاوا اسکریپت، isException روی true تنظیم می‌شود و value روی مقدار رشته‌ای شیء پرتاب‌شده تنظیم می‌شود.

پارامترها

  • عبارت

    رشته

    عبارتی برای ارزیابی.

  • گزینه‌ها

    شیء اختیاری

    پارامتر گزینه‌ها می‌تواند شامل یک یا چند گزینه باشد.

    • frameURL

      رشته اختیاری

      اگر مشخص شده باشد، عبارت در iframe که نشانی وب آن با نشانی وب مشخص‌شده مطابقت دارد ارزیابی می‌شود. به‌طور پیش‌فرض، عبارت در قاب بالایی صفحه بازرسی‌شده ارزیابی می‌شود.

    • scriptExecutionContext

      رشته اختیاری

      Chrome نسخه ۱۰۷ و بالاتر

      عبارت را در بافت دستورگان محتوای افزونه‌ای که با مبدأ مشخص‌شده مطابقت دارد ارزیابی می‌کند. اگر ارائه شود، scriptExecutionContext تنظیم «true» را در useContentScriptContext لغو می‌کند.

    • useContentScriptContext

      بولی اختیاری

      عبارت را در زمینه متن محتوای افزونه تماس‌گیرنده ارزیابی کنید، مشروط بر اینکه متن محتوا قبلاً به صفحه بازرسی‌شده تزریق شده باشد. اگر نه، عبارت ارزیابی نمی‌شود و فراخوانی با پارامتر استثنایی که روی شیئی تنظیم شده است که فیلد isError آن روی true و فیلد code آن روی E_NOTFOUND تنظیم شده است، فراخوانی می‌شود.

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به‌صورت زیر است: 

    (response: object) => void

    • پاسخ

      شیء

      Chrome نسخه ۱۵۱ و بالاتر

      نتیجه ارزیابی و اطلاعات استثنا.

      • exceptionInfo

        شیء

        شیئی که جزئیات را ارائه می‌دهد اگر استثنایی هنگام ارزیابی عبارت رخ دهد.

        • کد

          رشته

          اگر خطا در سمت DevTools قبل‌از ارزیابی عبارت رخ داده باشد، تنظیم می‌شود.

        • description

          رشته

          اگر خطا در سمت DevTools قبل‌از ارزیابی عبارت رخ داده باشد، تنظیم می‌شود.

        • جزئیات

          any[]

          اگر خطا در سمت DevTools قبل‌از ارزیابی عبارت رخ داده باشد، تنظیم می‌شود و حاوی آرایه‌ای از مقادیر است که ممکن است در رشته شرح جایگزین شود تا اطلاعات بیشتری درباره علت خطا ارائه دهد.

        • isError

          بولی

          اگر خطا در سمت DevTools قبل‌از ارزیابی عبارت رخ داده باشد، تنظیم می‌شود.

        • isException

          بولی

          اگر کد ارزیابی‌شده استثنای مدیریت‌نشده‌ای ایجاد کند، تنظیم می‌شود.

        • مقدار

          رشته

          اگر کد ارزیابی‌شده استثنای مدیریت‌نشده‌ای ایجاد کند، تنظیم می‌شود.

      • نتیجه

        شیء

        نتیجه ارزیابی.

بازگشتی‌ها

  • Promise<object>

    Chrome نسخه ۱۵۱ و بالاتر

    تابعی که پس‌از تکمیل ارزیابی فراخوانی می‌شود.

    ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

getResources()

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

فهرست منابع را از صفحه بازرسی‌شده بازیابی می‌کند.

پارامترها

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به‌صورت زیر است: 

    (resources: Resource[]) => void

    • منابع

      منبع[]

      منابع موجود در صفحه.

بازگشتی‌ها

  • Promise<Resource[]>

    Chrome نسخه ۱۵۱ و بالاتر

    تابعی که پس‌از تکمیل درخواست، فهرست منابع را دریافت می‌کند.

    ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

reload()

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

صفحه بازرسی‌شده را مجدداً بار می‌کند.

پارامترها

  • reloadOptions

    شیء اختیاری

    • ignoreCache

      بولی اختیاری

      وقتی درست باشد، بارکننده حافظه نهان را برای همه منابع صفحه بازرسی‌شده که قبل‌از فعال شدن رویداد load بار شده‌اند دور می‌زند. این اثر مشابه فشار دادن Ctrl+Shift+R در پنجره بازرسی‌شده یا در پنجره «ابزارهای توسعه‌دهنده» است.

    • injectedScript

      رشته اختیاری

      اگر مشخص شود، اسکریپت بلافاصله پس‌از بار شدن، قبل‌از هرکدام از اسکریپت‌های قاب، به هر قاب صفحه بازرسی‌شده تزریق خواهد شد. پس‌از بار کردن مجدد بعدی، اسکریپت تزریق نخواهد شد—برای مثال، اگر کاربر Ctrl+R را فشار دهد.

    • userAgent

      رشته اختیاری

      درصورت مشخص شدن، این رشته مقدار سرایند HTTP User-Agent را که هنگام بار کردن منابع صفحه بازرسی‌شده ارسال می‌شود لغو می‌کند. این رشته همچنین مقدار ویژگی navigator.userAgent را که به هر اسکریپت درحال اجرا در صفحه بازرسی‌شده برگردانده می‌شود لغو می‌کند.

رویدادها

onResourceAdded

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

وقتی منبع جدیدی به صفحه بازرسی‌شده اضافه می‌شود، فعال می‌شود.

پارامترها

  • تماس برگشتی

    عملکرد

    پارامتر callback به‌صورت زیر است: 

    (resource: Resource) => void

onResourceContentCommitted

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

وقتی نسخه جدیدی از منبع ثبت می‌شود (مثلاً کاربر نسخه ویرایش‌شده منبع را در «ابزارهای توسعه‌دهنده» ذخیره می‌کند) فعال می‌شود.

پارامترها

  • تماس برگشتی

    عملکرد

    پارامتر callback به‌صورت زیر است: 

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