این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

chrome.debugger

توضیحات

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

Chrome 125+

شناسه جلسه اشکال زدا. یکی از tabId، extensionId یا targetId باید مشخص شود. علاوه بر این، یک sessionId اختیاری می تواند ارائه شود. اگر sessionId برای آرگومان های ارسال شده از onEvent مشخص شده باشد، به این معنی است که رویداد از یک جلسه پروتکل فرزند در جلسه اشکال زدایی ریشه می آید. اگر sessionId هنگام ارسال به sendCommand مشخص شود، یک جلسه پروتکل فرزند در جلسه اشکال زدایی ریشه را هدف قرار می دهد.

خواص

شناسه extension
رشته اختیاری
شناسه افزونه‌ای که می‌خواهید اشکال‌زدایی کنید. پیوست کردن به صفحه پس‌زمینه افزونه تنها زمانی امکان‌پذیر است که از سوئیچ خط فرمان --silent-debugger-extension-api استفاده شود.
sessionId
رشته اختیاری
شناسه مات جلسه پروتکل Chrome DevTools. یک جلسه فرزند را در جلسه ریشه شناسایی می کند که توسط tabId، extensionId یا targetId شناسایی شده است.
tabId
شماره اختیاری
شناسه برگه ای که می خواهید اشکال زدایی کنید.
شناسه هدف
رشته اختیاری
شناسه مات هدف رفع اشکال.

DetachReason

Chrome 44+

دلیل قطع اتصال

Enum

"هدف_بسته"

"cancelled_by_user"

TargetInfo

اشکال زدایی اطلاعات هدف

خواص

پیوست شده است
بولی
درست است اگر دیباگر قبلاً پیوست شده باشد.
شناسه extension
رشته اختیاری
شناسه برنامه افزودنی، اگر نوع = 'background_page' تعریف شود.
faviconUrl
رشته اختیاری
URL فاویکون را هدف قرار دهید.
شناسه
رشته
شناسه هدف
tabId
شماره اختیاری
شناسه برگه که در صورت نوع == 'page' تعریف شده است.
عنوان
رشته
عنوان صفحه مورد نظر
نوع
TargetInfoType
نوع هدف
آدرس اینترنتی
رشته
URL هدف.

TargetInfoType

Chrome 44+

نوع هدف

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,
)

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

پارامترها

هدف
DebuggerSession
اشکال زدایی هدفی که می خواهید دستور را به آن ارسال کنید.
روش
رشته
نام روش باید یکی از روش هایی باشد که توسط پروتکل رفع اشکال از راه دور تعریف شده است.
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
```
- منبع
  اشکال زدایی
- دلیل
  DetachReason

onEvent

chrome.debugger.onEvent.addListener(
  callback: function,
)

هر زمان که خطایابی هدف رویداد ابزار دقیق را صادر می کند، شلیک می شود.

پارامترها

پاسخ به تماس
تابع
پارامتر callback به نظر می رسد:
```
(source: DebuggerSession, method: string, params?: object) => void
```
- منبع
  DebuggerSession
- روش
  رشته
- پارامترها
  شی اختیاری