chrome.devtools.inspectedWindow

توضیحات

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

آشکار

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

"devtools_page"

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

برای آشنایی کلی با استفاده از Developer Tools APIs به خلاصه DevTools APIs مراجعه کنید.

نمای کلی

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

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

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

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

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

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

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

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

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

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

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);
    }
  }
);

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

انواع

Resource

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

خواص

  • آدرس اینترنتی

    رشته

    URL منبع.

  • دریافت محتوا

    باطل

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

    تابع getContent به شکل زیر است: 

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

    • پاسخ به تماس

      تابع

      پارامتر callback به نظر می رسد: 

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

      • محتوا

        رشته

        محتوای منبع (بالقوه رمزگذاری شده).

      • رمزگذاری

        رشته

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

  • setContent

    باطل

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

    تابع setContent به شکل زیر است: 

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

    • محتوا

      رشته

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

    • متعهد شدن

      بولی

      درست است اگر کاربر ویرایش منبع را به پایان رسانده باشد و محتوای جدید منبع باید حفظ شود. اگر این یک تغییر جزئی باشد که کاربر در حال ویرایش منبع ارسال شده است نادرست است.

    • پاسخ به تماس

      عملکرد اختیاری

      پارامتر callback به نظر می رسد: 

      (error?: object) => void

      • خطا

        شی اختیاری

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

خواص

tabId

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

تایپ کنید

شماره

روش ها

eval()

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

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

پارامترها

  • بیان

    رشته

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

  • گزینه ها

    شی اختیاری

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

    • frameURL

      رشته اختیاری

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

    • scriptExecutionContext

      رشته اختیاری

      Chrome 107+

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

    • useContentScriptContext

      بولی اختیاری

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

  • پاسخ به تماس

    عملکرد اختیاری

    پارامتر callback به نظر می رسد: 

    (result: object, exceptionInfo: object) => void

    • نتیجه

      شی

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

    • استثنا اطلاعات

      شی

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

      • کد

        رشته

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

      • توضیحات

        رشته

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

      • جزئیات

        هر[]

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

      • خطا است

        بولی

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

      • استثنا است

        بولی

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

      • ارزش

        رشته

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

getResources()

chrome.devtools.inspectedWindow.getResources(
  callback: function,
)

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

پارامترها

  • پاسخ به تماس

    تابع

    پارامتر callback به نظر می رسد: 

    (resources: Resource[]) => void

    • منابع

      منبع []

      منابع داخل صفحه

reload()

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

صفحه بازرسی شده را دوباره بارگیری می کند.

پارامترها

  • گزینه های بارگذاری مجدد

    شی اختیاری

    • ignoreCache

      بولی اختیاری

      زمانی که درست باشد، لودر کش را برای تمام منابع صفحه بازرسی شده که قبل از اجرا شدن رویداد load بارگیری شده اند، دور می زند. این افکت شبیه فشار دادن Ctrl+Shift+R در پنجره بازرسی شده یا در پنجره Developer Tools است.

    • 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