chrome.debugger

توضیحات

رابط برنامه‌نویسی کاربردی chrome.debugger به عنوان یک ابزار جایگزین برای پروتکل اشکال‌زدایی از راه دور کروم عمل می‌کند. از chrome.debugger برای اتصال به یک یا چند تب به منظور بررسی تعامل شبکه، اشکال‌زدایی جاوا اسکریپت، تغییر DOM و CSS و موارد دیگر استفاده کنید. از ویژگی Debuggee tabId برای هدف‌گیری تب‌ها با sendCommand و مسیریابی رویدادها توسط tabId از فراخوانی‌های onEvent استفاده کنید.

مجوزها

debugger

برای استفاده از این API، باید مجوز "debugger" را در مانیفست افزونه خود اعلام کنید.

{
  "name": "My extension",
  ...
  "permissions": [
    "debugger",
  ],
  ...
}

مفاهیم و کاربردها

پس از اتصال، API chrome.debugger به شما امکان می‌دهد دستورات پروتکل توسعه‌دهندگان کروم (CDP) را به یک هدف مشخص ارسال کنید. توضیح عمیق CDP خارج از محدوده این مستندات است - برای کسب اطلاعات بیشتر در مورد CDP، مستندات رسمی CDP را بررسی کنید.

اهداف

تارگت‌ها (targets) نشان‌دهنده چیزی هستند که در حال اشکال‌زدایی است - این می‌تواند شامل یک تب، یک iframe یا یک worker باشد. هر تارگت توسط یک UUID شناسایی می‌شود و یک نوع مرتبط (مانند iframe ، shared_worker و موارد دیگر) دارد.

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

دامنه‌های محدود شده

به دلایل امنیتی، API chrome.debugger دسترسی به همه دامنه‌های پروتکل Chrome DevTools را فراهم نمی‌کند. دامنه‌های موجود عبارتند از: Accessibility ، Audits ، CacheStorage ، Console ، CSS ، Database ، Debugger ، DOM ، DOMDebugger ، DOMSnapshot ، Emulation ، Fetch ، IO ، Input ، Inspector ، Log ، Network ، Overlay ، Page ، Performance ، Profiler ، Runtime ، Storage ، Target ، Tracing ، WebAudio و WebAuthn .

با قاب‌ها کار کنید

نگاشت یک به یک فریم‌ها به اهداف وجود ندارد. در یک تب، چندین فریم فرآیند مشابه ممکن است هدف یکسانی را به اشتراک بگذارند اما از زمینه اجرایی متفاوتی استفاده کنند. از سوی دیگر، ممکن است یک هدف جدید برای یک iframe خارج از فرآیند ایجاد شود.

برای اتصال به همه فریم‌ها، باید هر نوع فریم را جداگانه مدیریت کنید:

• به رویداد Runtime.executionContextCreated گوش دهید تا زمینه‌های اجرایی جدید مرتبط با فریم‌های فرآیند مشابه را شناسایی کنید.

• مراحل اتصال به اهداف مرتبط را دنبال کنید تا فریم‌های خارج از فرآیند شناسایی شوند.

به اهداف مرتبط متصل شوید

پس از اتصال به یک هدف، ممکن است بخواهید به اهداف مرتبط بیشتری از جمله فریم‌های فرزند خارج از فرآیند یا workerهای مرتبط متصل شوید.

از کروم ۱۲۵ به بعد، API مربوط به chrome.debugger از جلسات مسطح (flat sessions) پشتیبانی می‌کند. این به شما امکان می‌دهد تا اهداف اضافی را به عنوان فرزند به جلسه اشکال‌زدای اصلی خود اضافه کنید و بدون نیاز به فراخوانی مجدد 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 }]
});

اتصال خودکار فقط به فریم‌هایی متصل می‌شود که هدف از وجود آنها آگاه است، که محدود به فریم‌هایی است که فرزندان بلافصل یک فریم مرتبط با آن هستند. برای مثال، با سلسله مراتب فریم A -> B -> C (که همه آنها cross-origin هستند)، فراخوانی Target.setAutoAttach برای هدف مرتبط با A منجر به اتصال session به B نیز می‌شود. با این حال، این بازگشتی نیست، بنابراین Target.setAutoAttach نیز باید برای اتصال session به C فراخوانی شود.

مثال‌ها

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

انواع

Debuggee

شناسه اشکال‌زدایی. باید tabId، extensionId یا targetId مشخص شود.

خواص

• شناسه افزونه

  رشته اختیاری

  شناسه افزونه‌ای که قصد اشکال‌زدایی آن را دارید. اتصال به صفحه پس‌زمینه افزونه فقط زمانی امکان‌پذیر است که از سوئیچ خط فرمان --silent-debugger-extension-api استفاده شود.

• شناسه برگه

  شماره اختیاری

  شناسه‌ی برگه‌ای که قصد اشکال‌زدایی آن را دارید.

• شناسه هدف

  رشته اختیاری

  شناسه‌ی غیرشفافِ هدفِ اشکال‌زدایی.

DebuggerSession

کروم ۱۲۵+

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

خواص

• شناسه افزونه

  رشته اختیاری

  شناسه افزونه‌ای که قصد اشکال‌زدایی آن را دارید. اتصال به صفحه پس‌زمینه افزونه فقط زمانی امکان‌پذیر است که از سوئیچ خط فرمان --silent-debugger-extension-api استفاده شود.

• شناسه جلسه

  رشته اختیاری

  شناسه‌ی غیرشفافِ نشست پروتکل Chrome DevTools. یک نشست فرزند را در نشست ریشه که با tabId، extensionId یا targetId شناسایی می‌شود، شناسایی می‌کند.

• شناسه برگه

  شماره اختیاری

  شناسه‌ی برگه‌ای که قصد اشکال‌زدایی آن را دارید.

• شناسه هدف

  رشته اختیاری

  شناسه‌ی غیرشفافِ هدفِ اشکال‌زدایی.

DetachReason

کروم ۴۴+

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

شمارشی

"هدف_بسته"

"لغو_توسط_کاربر"

TargetInfo

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

خواص

• پیوست

  بولی

  اگر اشکال‌زدا از قبل پیوست شده باشد، صحیح است.

• شناسه افزونه

  رشته اختیاری

  شناسه افزونه، که در صورت نوع = 'background_page' تعریف می‌شود.

• آدرس فاویکون

  رشته اختیاری

  آدرس فاویکون هدف.

• شناسه

  رشته

  شناسه هدف.

• شناسه برگه

  شماره اختیاری

  شناسه برگه، که در صورت نوع == 'صفحه' تعریف می‌شود.

• عنوان

  رشته

  عنوان صفحه هدف.

• نوع

  نوع اطلاعات هدف

  نوع هدف.

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

  رشته

  آدرس اینترنتی هدف.

TargetInfoType

کروم ۴۴+

نوع هدف.

شمارشی

«صفحه»

"صفحه_پس_زمینه"

"کارگر"

«دیگر»

روش‌ها

attach()

chrome.debugger.attach(
  target: Debuggee,
  requiredVersion: string,
): Promise<void>

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

پارامترها

• هدف

  دیباگی

  هدف اشکال‌زدایی که می‌خواهید به آن متصل شوید.

• نسخه مورد نیاز

  رشته

  نسخه پروتکل اشکال‌زدایی مورد نیاز ("0.1"). فقط می‌توان نسخه اصلی منطبق و نسخه فرعی بزرگتر یا مساوی را به دیباگ پیوست کرد. فهرست نسخه‌های پروتکل را می‌توان از اینجا دریافت کرد.

بازگشت‌ها

• قول<void>

  کروم ۹۶+

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

detach()

chrome.debugger.detach(
  target: Debuggee,
): Promise<void>

اشکال‌زدا را از هدف داده شده جدا می‌کند.

پارامترها

• هدف

  دیباگی

  اشکال‌زدایی هدفی که می‌خواهید از آن جدا شوید.

بازگشت‌ها

• قول<void>

  کروم ۹۶+

  زمانی که عملیات detach با موفقیت یا شکست مواجه شود، برطرف می‌شود. promise بدون هیچ مقداری برطرف می‌شود. اگر detach با شکست مواجه شود، promise رد خواهد شد.

getTargets()

chrome.debugger.getTargets(): Promise<TargetInfo[]>

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

بازگشت‌ها

• قول< TargetInfo []>

  کروم ۹۶+

sendCommand()

chrome.debugger.sendCommand(
  target: DebuggerSession,
  method: string,
  commandParams?: object,
): Promise<object | undefined>

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

پارامترها

• هدف

  جلسه اشکال‌زدایی

  اشکال‌زدایی مقصدی که می‌خواهید دستور را به آن ارسال کنید.

• روش

  رشته

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

• پارامترهای فرمان

  شیء اختیاری

  شیء JSON با پارامترهای درخواست. این شیء باید با طرح پارامترهای اشکال‌زدایی از راه دور برای روش داده شده مطابقت داشته باشد.

بازگشت‌ها

• قول <object | undefined>

  کروم ۹۶+

  بدنه پاسخ. اگر هنگام ارسال پیام خطایی رخ دهد، promise رد خواهد شد.

رویدادها

onDetach

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

زمانی اجرا می‌شود که مرورگر، جلسه اشکال‌زدایی (debugging session) مربوط به تب را خاتمه می‌دهد. این اتفاق زمانی می‌افتد که یا تب بسته می‌شود یا Chrome DevTools برای تب پیوست شده فراخوانی می‌شود.

پارامترها

• تماس برگشتی

  تابع

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

  (source: Debuggee, reason: DetachReason) => void

  • منبع

    دیباگی

  • دلیل

    دلیل جدا کردن

onEvent

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

هر زمان که اشکال‌زدایی مسائل هدف، رویداد ابزار دقیق را نشان دهد، اجرا می‌شود.

پارامترها

• تماس برگشتی

  تابع

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

  (source: DebuggerSession, method: string, params?: object) => void

  • منبع

    جلسه اشکال‌زدایی

  • روش

    رشته

  • پارامترها

    شیء اختیاری