توضیحات
chrome.debugger
API به عنوان یک انتقال جایگزین برای پروتکل اشکالزدایی از راه دور Chrome عمل میکند. از chrome.debugger
برای اتصال به یک یا چند برگه برای تعامل شبکه ابزار، اشکال زدایی جاوا اسکریپت، جهش در DOM و CSS و موارد دیگر استفاده کنید. از ویژگی Debuggee
tabId
برای هدفیابی برگههای sendCommand
و مسیریابی رویدادها توسط tabId
از تماسهای onEvent
استفاده کنید.
مجوزها
debugger
برای استفاده از این API باید مجوز "debugger"
را در مانیفست برنامه افزودنی خود اعلام کنید.
{
"name": "My extension",
...
"permissions": [
"debugger",
],
...
}
مفاهیم و کاربرد
پس از اتصال، API chrome.debugger
به شما امکان میدهد دستورات پروتکل ابزار توسعه کروم (CDP) را به یک هدف معین ارسال کنید. توضیح عمیق CDP خارج از محدوده این مستندات است - برای کسب اطلاعات بیشتر در مورد CDP ، اسناد رسمی CDP را بررسی کنید.
اهداف
اهداف نشان دهنده چیزی است که در حال رفع اشکال است - این می تواند شامل یک برگه، یک iframe یا یک کارگر باشد. هر هدف توسط یک UUID شناسایی میشود و دارای یک نوع مرتبط است (مانند iframe
، shared_worker
و موارد دیگر).
در یک هدف، ممکن است چندین زمینه اجرایی وجود داشته باشد - برای مثال iframe های فرآیندی یک هدف منحصر به فرد دریافت نمی کنند، اما در عوض به عنوان زمینه های مختلف نشان داده می شوند که می توان از یک هدف واحد به آنها دسترسی داشت.
دامنه های محدود
به دلایل امنیتی، API chrome.debugger
دسترسی به همه دامنههای پروتکل ابزار توسعه کروم را فراهم نمیکند. دامنههای موجود عبارتند از : دسترسی ، ممیزی ، ذخیرهسازی حافظه پنهان ، کنسول ، CSS ، پایگاه داده ، اشکالزدا ، DOM ، DOMDebugger ، DOMSnapshot ، شبیهسازی ، Fetch ، IO ، ورودی ، Inspector ، Log ، Network ، Overlay ، صفحه ، زمان ، عملکرد ، عملکرد , Target , Tracing , WebAudio و WebAuthn .
با قاب کار کنید
یک نگاشت یک به یک از فریم ها به اهداف وجود ندارد. در یک برگه واحد، چندین فریم فرآیند مشابه ممکن است هدف یکسانی را به اشتراک بگذارند اما از یک زمینه اجرای متفاوت استفاده کنند. از سوی دیگر، ممکن است یک هدف جدید برای یک iframe خارج از فرآیند ایجاد شود.
برای اتصال به همه قاب ها، باید هر نوع قاب را جداگانه مدیریت کنید:
به رویداد
Runtime.executionContextCreated
گوش دهید تا زمینه های اجرای جدید مرتبط با فریم های فرآیند مشابه را شناسایی کنید.مراحل اتصال به اهداف مرتبط را برای شناسایی فریم های خارج از فرآیند دنبال کنید.
به اهداف مرتبط وصل کنید
پس از اتصال به یک هدف، ممکن است بخواهید به اهداف مرتبط دیگری از جمله فریم های فرزند خارج از فرآیند یا کارگران مرتبط متصل شوید.
با شروع در Chrome 125، API chrome.debugger
از جلسات مسطح پشتیبانی میکند. این به شما امکان میدهد اهداف دیگری را در کودکی به جلسه اصلی اشکالزدای خود اضافه کنید و بدون نیاز به تماس دیگری با chrome.debugger.attach
به آنها پیام دهید. درعوض، میتوانید هنگام فراخوانی chrome.debugger.sendCommand
یک ویژگی sessionId
اضافه کنید تا هدف فرزندی را که میخواهید فرمانی به آن ارسال کنید شناسایی کنید.
برای پیوست کردن خودکار به فریمهای فرزند خارج از فرآیند، ابتدا یک شنونده برای رویداد Target.attachedToTarget
اضافه کنید:
chrome.debugger.onEvent.addListener((source, method, params) => {
if (method === "Target.attachedToTarget") {
// `source` identifies the parent session, but we need to construct a new
// identifier for the child session
const session = { ...source, sessionId: params.sessionId };
// Call any needed CDP commands for the child session
await chrome.debugger.sendCommand(session, "Runtime.enable");
}
});
سپس، با ارسال دستور Target.setAutoAttach
با گزینه flatten
که روی true
تنظیم شده است ، اتصال خودکار را فعال کنید:
await chrome.debugger.sendCommand({ tabId }, "Target.setAutoAttach", {
autoAttach: true,
waitForDebuggerOnStart: false,
flatten: true,
filter: [{ type: "iframe", exclude: false }]
});
نمونه ها
برای امتحان این API، نمونه Debugger API را از مخزن chrome-extension-samples نصب کنید.
انواع
Debuggee
شناسه اشکال زدایی باید tabId، extensionId یا targetId مشخص شود
خواص
- شناسه extension
رشته اختیاری
شناسه افزونهای که میخواهید اشکالزدایی کنید. پیوست کردن به صفحه پسزمینه افزونه تنها زمانی امکانپذیر است که از سوئیچ خط فرمان
--silent-debugger-extension-api
استفاده شود. - tabId
شماره اختیاری
شناسه برگه ای که می خواهید اشکال زدایی کنید.
- شناسه هدف
رشته اختیاری
شناسه مات هدف رفع اشکال.
DebuggerSession
شناسه جلسه اشکال زدا. یکی از tabId، extensionId یا targetId باید مشخص شود. علاوه بر این، یک sessionId اختیاری می تواند ارائه شود. اگر sessionId برای آرگومان های ارسال شده از onEvent
مشخص شده باشد، به این معنی است که رویداد از یک جلسه پروتکل فرزند در جلسه اشکال زدایی ریشه می آید. اگر sessionId هنگام ارسال به sendCommand
مشخص شود، یک جلسه پروتکل فرزند در جلسه اشکال زدایی ریشه را هدف قرار می دهد.
خواص
- شناسه extension
رشته اختیاری
شناسه افزونهای که میخواهید اشکالزدایی کنید. پیوست کردن به صفحه پسزمینه افزونه تنها زمانی امکانپذیر است که از سوئیچ خط فرمان
--silent-debugger-extension-api
استفاده شود. - sessionId
رشته اختیاری
شناسه مات جلسه پروتکل Chrome DevTools. یک جلسه فرزند را در جلسه ریشه شناسایی می کند که توسط tabId، extensionId یا targetId شناسایی شده است.
- tabId
شماره اختیاری
شناسه برگه ای که می خواهید اشکال زدایی کنید.
- شناسه هدف
رشته اختیاری
شناسه مات هدف رفع اشکال.
DetachReason
دلیل قطع اتصال
Enum
"هدف_بسته" "cancelled_by_user"
TargetInfo
اشکال زدایی اطلاعات هدف
خواص
- پیوست شده است
بولی
درست است اگر دیباگر قبلاً پیوست شده باشد.
- شناسه extension
رشته اختیاری
شناسه برنامه افزودنی، اگر نوع = 'background_page' تعریف شود.
- faviconUrl
رشته اختیاری
URL فاویکون را هدف قرار دهید.
- شناسه
رشته
شناسه هدف
- tabId
شماره اختیاری
شناسه برگه که در صورت نوع == 'page' تعریف شده است.
- عنوان
رشته
عنوان صفحه مورد نظر
- نوع
نوع هدف
- آدرس اینترنتی
رشته
URL هدف.
TargetInfoType
نوع هدف
Enum
"صفحه" "background_page" "کارگر" "دیگر"
روش ها
attach()
chrome.debugger.attach(
target: Debuggee,
requiredVersion: string,
callback?: function,
)
دیباگر را به هدف داده شده متصل می کند.
پارامترها
- هدف
اشکال زدایی هدفی که می خواهید به آن پیوست کنید.
- نسخه مورد نیاز
رشته
نسخه پروتکل اشکال زدایی مورد نیاز ("0.1"). فقط می توان با نسخه اصلی منطبق و نسخه کوچک بزرگتر یا مساوی به اشکال زدایی متصل شد. لیست نسخه های پروتکل را می توان از اینجا دریافت کرد.
- پاسخ به تماس
عملکرد اختیاری
پارامتر
callback
به نظر می رسد:() => void
برمی گرداند
قول<باطل>
Chrome 96+Promises در Manifest V3 و نسخه های جدیدتر پشتیبانی می شود، اما callbacks برای سازگاری به عقب ارائه شده است. شما نمی توانید از هر دو در یک فراخوانی تابع استفاده کنید. وعده با همان نوعی که به callback ارسال می شود حل می شود.
detach()
chrome.debugger.detach(
target: Debuggee,
callback?: function,
)
دیباگر را از هدف داده شده جدا می کند.
پارامترها
- هدف
اشکال زدایی هدفی که می خواهید از آن جدا شوید.
- پاسخ به تماس
عملکرد اختیاری
پارامتر
callback
به نظر می رسد:() => void
برمی گرداند
قول<باطل>
Chrome 96+Promises در Manifest V3 و نسخه های جدیدتر پشتیبانی می شود، اما callbacks برای سازگاری به عقب ارائه شده است. شما نمی توانید از هر دو در یک فراخوانی تابع استفاده کنید. وعده با همان نوعی که به callback ارسال می شود حل می شود.
getTargets()
chrome.debugger.getTargets(
callback?: function,
)
لیستی از اهداف اشکال زدایی موجود را برمی گرداند.
پارامترها
- پاسخ به تماس
عملکرد اختیاری
پارامتر
callback
به نظر می رسد:(result: TargetInfo[]) => void
- نتیجه
TargetInfo []
آرایه ای از اشیاء TargetInfo مربوط به اهداف اشکال زدایی موجود.
برمی گرداند
Promise< TargetInfo []>
Chrome 96+Promises در Manifest V3 و نسخه های جدیدتر پشتیبانی می شود، اما callbacks برای سازگاری به عقب ارائه شده است. شما نمی توانید از هر دو در یک فراخوانی تابع استفاده کنید. وعده با همان نوعی که به callback ارسال می شود حل می شود.
sendCommand()
chrome.debugger.sendCommand(
target: DebuggerSession,
method: string,
commandParams?: object,
callback?: function,
)
دستور داده شده را به هدف اشکال زدایی می فرستد.
پارامترها
- هدف
اشکال زدایی هدفی که می خواهید دستور را به آن ارسال کنید.
- روش
رشته
نام روش باید یکی از روش هایی باشد که توسط پروتکل رفع اشکال از راه دور تعریف شده است.
- commandparams
شی اختیاری
شی JSON با پارامترهای درخواست. این شی باید با طرح پارامترهای اشکال زدایی راه دور برای روش داده شده مطابقت داشته باشد.
- پاسخ به تماس
عملکرد اختیاری
پارامتر
callback
به نظر می رسد:(result?: object) => void
- نتیجه
شی اختیاری
شی JSON با پاسخ. ساختار پاسخ بسته به نام روش متفاوت است و با ویژگی 'returns' توضیحات فرمان در پروتکل اشکال زدایی راه دور تعریف می شود.
برمی گرداند
قول<object | تعریف نشده>
Chrome 96+Promises در Manifest V3 و نسخه های جدیدتر پشتیبانی می شود، اما callbacks برای سازگاری به عقب ارائه شده است. شما نمی توانید از هر دو در یک فراخوانی تابع استفاده کنید. وعده با همان نوعی که به callback ارسال می شود حل می شود.
رویدادها
onDetach
chrome.debugger.onDetach.addListener(
callback: function,
)
هنگامی که مرورگر جلسه اشکال زدایی را برای برگه خاتمه می دهد فعال می شود. این زمانی اتفاق میافتد که یا برگه بسته میشود یا Chrome DevTools برای برگه پیوست شده فراخوانی میشود.
پارامترها
- پاسخ به تماس
تابع
پارامتر
callback
به نظر می رسد:(source: Debuggee, reason: DetachReason) => void
- منبع
- دلیل
onEvent
chrome.debugger.onEvent.addListener(
callback: function,
)
هر زمان که خطایابی هدف رویداد ابزار دقیق را صادر می کند، شلیک می شود.
پارامترها
- پاسخ به تماس
تابع
پارامتر
callback
به نظر می رسد:(source: DebuggerSession, method: string, params?: object) => void
- منبع
- روش
رشته
- پارامترها
شی اختیاری