chrome.devtools.inspectedWindow

توضیحات

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

مانیفست

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

"devtools_page"

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

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

نمای کلی

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

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

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

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

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

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

  • متد eval از یک دنیای ایزوله برای کدی که ارزیابی می‌شود استفاده نمی‌کند، بنابراین وضعیت جاوا اسکریپت پنجره‌ی بازرسی شده برای کد قابل دسترسی است. از این متد زمانی استفاده کنید که دسترسی به وضعیت جاوا اسکریپت صفحه‌ی بازرسی شده مورد نیاز است.
  • زمینه اجرای کدی که ارزیابی می‌شود شامل API کنسول Developer Tools است. برای مثال، کد می‌تواند 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);
    }
  }
);

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

انواع

Resource

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

خواص

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

    رشته

    آدرس اینترنتی منبع.

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

    باطل

    وعده

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

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

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

    • تماس برگشتی

      تابع اختیاری

      پارامتر callback به شکل زیر است: 

      (response: object) => void

      • پاسخ

        شیء

        در حال بررسی

        یک شیء شامل محتوای منبع و کدگذاری آن.

        • محتوا

          رشته

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

        • کدگذاری

          رشته

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

    • بازده

      قول دادن<object>

      در حال بررسی

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

      Promiseها فقط برای Manifest V3 و نسخه‌های بعدی پشتیبانی می‌شوند، سایر پلتفرم‌ها باید از callbackها استفاده کنند.

  • تنظیم محتوا

    باطل

    وعده

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

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

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

    • محتوا

      رشته

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

    • مرتکب شدن

      بولی

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

    • تماس برگشتی

      تابع اختیاری

      پارامتر callback به شکل زیر است: 

      (error?: object) => void

      • خطا

        شیء اختیاری

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

    • بازده

      قول دادن<object>

      در حال بررسی

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

      Promiseها فقط برای Manifest V3 و نسخه‌های بعدی پشتیبانی می‌شوند، سایر پلتفرم‌ها باید از callbackها استفاده کنند.

خواص

tabId

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

نوع

شماره

روش‌ها

eval()

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

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

پارامترها

  • بیان

    رشته

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

  • گزینه‌ها

    شیء اختیاری

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

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

      رشته اختیاری

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

    • scriptExecutionContext

      رشته اختیاری

      کروم ۱۰۷+

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

    • استفاده ازContentScriptContext

      بولی اختیاری

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

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به شکل زیر است: 

    (response: object) => void

    • پاسخ

      شیء

      در حال بررسی

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

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

        شیء

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

        • کد

          رشته

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

        • توضیحات

          رشته

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

        • جزئیات

          هر []

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

        • خطا

          بولی

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

        • استثنا

          بولی

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

        • ارزش

          رشته

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

      • نتیجه

        شیء

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

بازگشت‌ها

  • قول دادن<object>

    در حال بررسی

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

    Promiseها فقط برای Manifest V3 و نسخه‌های بعدی پشتیبانی می‌شوند، سایر پلتفرم‌ها باید از callbackها استفاده کنند.

getResources()

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

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

پارامترها

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به شکل زیر است: 

    (resources: Resource[]) => void

    • منابع

      منبع []

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

بازگشت‌ها

  • قول بده< منبع []>

    در حال بررسی

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

    Promiseها فقط برای Manifest V3 و نسخه‌های بعدی پشتیبانی می‌شوند، سایر پلتفرم‌ها باید از callbackها استفاده کنند.

reload()

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

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

پارامترها

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

    شیء اختیاری

    • نادیده گرفتن کش

      بولی اختیاری

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

    • اسکریپت تزریق‌شده

      رشته اختیاری

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

    • کاربر عامل

      رشته اختیاری

      در صورت مشخص شدن، رشته، مقدار هدر 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