chrome.debugger

الوصف

تعمل واجهة برمجة التطبيقات chrome.debugger كبروتوكول نقل بديل لبروتوكول تصحيح الأخطاء عن بُعد في Chrome. استخدِم chrome.debugger للربط بعلامة تبويب واحدة أو أكثر من أجل تسجيل تفاعلات الشبكة وتصحيح أخطاء JavaScript وتعديل DOM وCSS وغير ذلك. استخدِم السمة Debuggee tabId لاستهداف علامات التبويب التي تتضمّن sendCommand وتوجيه الأحداث حسب tabId من عمليات معاودة الاتصال onEvent.

الأذونات

debugger

يجب الإفصاح عن الإذن "debugger" في بيان الإضافة لاستخدام واجهة برمجة التطبيقات هذه.

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

المفاهيم والاستخدام

بعد ربطها، تتيح لك واجهة برمجة التطبيقات chrome.debugger إرسال أوامر بروتوكول أدوات مطوّري البرامج في Chrome (CDP) إلى هدف معيّن. لا تتناول هذه المستندات شرحًا تفصيليًا لمنصة CDP، ولكن يمكنك الاطّلاع على المستندات الرسمية حول منصة CDP لمعرفة المزيد.

الأهداف

تمثّل الأهداف عنصرًا يتم تصحيح أخطائه، ويمكن أن يشمل ذلك علامة تبويب أو إطار iframe أو عامل. يتم تحديد كل هدف من خلال معرّف فريد عالمي (UUID) وله نوع مرتبط (مثل iframe وshared_worker وغير ذلك).

ضمن هدف معيّن، قد تتوفّر سياقات تنفيذ متعدّدة، مثلاً، لا تحصل إطارات iframe التي تستخدم العملية نفسها على هدف فريد، بل يتم تمثيلها كسياقات مختلفة يمكن الوصول إليها من هدف واحد.

النطاقات المحظورة

لأسباب أمنية، لا تتيح واجهة برمجة التطبيقات chrome.debugger الوصول إلى جميع نطاقات بروتوكول Chrome DevTools. النطاقات المتاحة هي: إمكانية الوصول وعمليات التدقيق و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 لتحديد سياقات التنفيذ الجديدة المرتبطة بإطارات العملية نفسها.

  • اتّبِع الخطوات لربط اللقطات المستهدَفة ذات الصلة من أجل تحديد اللقطات التي تتم معالجتها خارج العملية.

بعد الربط بهدف، قد تحتاج إلى الربط بأهداف أخرى ذات صلة، بما في ذلك الإطارات الفرعية خارج العملية أو العناصر المرتبطة.

بدءًا من الإصدار 125 من Chrome، تتيح واجهة برمجة التطبيقات chrome.debugger الجلسات المسطّحة. يتيح لك ذلك إضافة أهداف إضافية كعناصر تابعة إلى جلسة تصحيح الأخطاء الرئيسية وإرسال رسائل إليها بدون الحاجة إلى إجراء مكالمة أخرى إلى chrome.debugger.attach. بدلاً من ذلك، يمكنك إضافة السمة sessionId عند استدعاء chrome.debugger.sendCommand لتحديد الجهاز المستهدَف الذي تريد إرسال أمر إليه.

لإرفاق إطار فرعي خارج العملية تلقائيًا، عليك أولاً إضافة أداة معالجة للحدث 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 لكي يتم ربط الجلسة بـ C.

أمثلة

لتجربة واجهة برمجة التطبيقات هذه، ثبِّت مثال واجهة برمجة التطبيقات الخاصة بأداة تصحيح الأخطاء من مستودع chrome-extension-samples.

الأنواع

Debuggee

معرّف برنامج تصحيح الأخطاء يجب تحديد tabId أو extensionId أو targetId

الخصائص

  • extensionId

    سلسلة اختيارية

    رقم تعريف الإضافة التي تريد تصحيح أخطائها. لا يمكن الربط بصفحة خلفية لإحدى الإضافات إلا عند استخدام خيار سطر الأوامر --silent-debugger-extension-api.

  • tabId

    number اختياري

    رقم تعريف علامة التبويب التي تريد تصحيح أخطائها.

  • targetId

    سلسلة اختيارية

    المعرّف غير الشفاف لهدف تصحيح الأخطاء.

DebuggerSession

الإصدار 125 من Chrome والإصدارات الأحدث

معرّف جلسة برنامج تصحيح الأخطاء يجب تحديد أحد الخيارات tabId أو extensionId أو targetId. بالإضافة إلى ذلك، يمكن تقديم sessionId اختياري. في حال تحديد sessionId للوسيطات المُرسَلة من onEvent، يعني ذلك أنّ الحدث وارد من جلسة بروتوكول فرعية ضمن جلسة التصحيح الرئيسية. إذا تم تحديد sessionId عند تمريره إلى sendCommand، سيستهدف جلسة بروتوكول فرعية ضمن جلسة تصحيح الأخطاء الرئيسية.

الخصائص

  • extensionId

    سلسلة اختيارية

    رقم تعريف الإضافة التي تريد تصحيح أخطائها. لا يمكن الربط بصفحة خلفية لإحدى الإضافات إلا عند استخدام خيار سطر الأوامر --silent-debugger-extension-api.

  • sessionId

    سلسلة اختيارية

    المعرّف المبهم لجلسة "بروتوكول أدوات مطوّري البرامج في Chrome". تحدّد جلسة ثانوية ضمن الجلسة الرئيسية التي يحدّدها tabId أو extensionId أو targetId.

  • tabId

    number اختياري

    رقم تعريف علامة التبويب التي تريد تصحيح أخطائها.

  • targetId

    سلسلة اختيارية

    المعرّف غير الشفاف لهدف تصحيح الأخطاء.

DetachReason

Chrome 44 والإصدارات الأحدث

سبب إنهاء الاتصال

Enum

"target_closed"

"canceled_by_user"

TargetInfo

معلومات تصحيح الأخطاء المستهدَفة

الخصائص

  • مرفق

    قيمة منطقية

    تكون القيمة صحيحة إذا كان مصحّح الأخطاء مرفقًا.

  • extensionId

    سلسلة اختيارية

    معرّف الإضافة، ويتم تحديده إذا كان النوع = "background_page".

  • faviconUrl

    سلسلة اختيارية

    تمثّل هذه السمة عنوان URL الخاص بالرمز المفضّل المستهدَف.

  • id

    سلسلة

    معرّف الهدف

  • tabId

    number اختياري

    معرّف علامة التبويب، يتم تحديده إذا كان النوع == "صفحة".

  • title

    سلسلة

    عنوان الصفحة المستهدَفة

  • النوع

    TargetInfoType

    نوع الاستهداف:

  • url

    سلسلة

    عنوان URL الهدف

TargetInfoType

Chrome 44 والإصدارات الأحدث

نوع الاستهداف:

Enum

"page"

"background_page"

"worker"

"other"

الطُرق

attach()

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

يربط أداة تصحيح الأخطاء بالهدف المحدّد.

المعلمات

  • عنصر تصحيح الأخطاء الذي تريد ربطه.

  • requiredVersion

    سلسلة

    إصدار بروتوكول تصحيح الأخطاء المطلوب ("0.1") لا يمكن ربط المصحّح إلا بالتطبيق الذي يتطابق رقمه مع رقم الإصدار الرئيسي ويكون رقم الإصدار الثانوي فيه أكبر أو يساوي رقم الإصدار الثانوي للمصحّح. يمكنك الاطّلاع على قائمة بإصدارات البروتوكول هنا.

المرتجعات

  • Promise<void>

    الإصدار 96 من Chrome والإصدارات الأحدث

detach()

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

يفصل أداة تصحيح الأخطاء عن الهدف المحدّد.

المعلمات

المرتجعات

  • Promise<void>

    الإصدار 96 من Chrome والإصدارات الأحدث

getTargets()

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

تعرِض هذه الطريقة قائمة بأهداف تصحيح الأخطاء المتاحة.

المرتجعات

  • Promise<TargetInfo[]>

    الإصدار 96 من Chrome والإصدارات الأحدث

sendCommand()

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

يرسل هذا الأمر الأمر المحدّد إلى هدف تصحيح الأخطاء.

المعلمات

  • الاستهداف

    DebuggerSession

    عنصر تصحيح الأخطاء الذي تريد إرسال الأمر إليه

  • method

    سلسلة

    اسم الطريقة يجب أن تكون إحدى الطرق المحدّدة في بروتوكول تصحيح الأخطاء عن بُعد.

  • commandParams

    العنصر اختياري

    عنصر JSON يتضمّن مَعلمات الطلب يجب أن يتوافق هذا العنصر مع مخطط مَعلمات تصحيح الأخطاء عن بُعد للطريقة المحدّدة.

المرتجعات

  • Promise<object | undefined>

    الإصدار 96 من Chrome والإصدارات الأحدث

الفعاليات

onDetach

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

يتم تنشيط هذا الحدث عندما ينهي المتصفّح جلسة تصحيح الأخطاء لعلامة التبويب. يحدث ذلك عند إغلاق علامة التبويب أو عند استدعاء "أدوات مطوّري Chrome" لعلامة التبويب المرفقة.

المعلمات

onEvent

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

يتم إطلاق هذا الحدث كلما حدثت مشكلة في أداة تصحيح الأخطاء.

المعلمات

  • callback

    دالة

    تظهر المَعلمة callback على النحو التالي: 

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

    • المصدر

      DebuggerSession

    • method

      سلسلة

    • المَعلمات

      العنصر اختياري