chrome.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 ، شبیه‌سازی ، واکشی ، IO ، ورودی ، بازرس ، گزارش ، شبکه ، پوشش ، صفحه ، زمان‌بندی ، عملکرد ، عملکرد , 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 }]
});

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

نمونه ها

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

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

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

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

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

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

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