browser.debugger

الوصف

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

الأذونات

debugger

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

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

القيود المفروضة على سياسات المؤسسة

على أجهزة المؤسسة، يمكن أن تمنع بعض السياسات الإضافات من ربط أداة تصحيح الأخطاء باستخدام نموذج "الكل أو لا شيء" في وقت الربط (browser.debugger.attach()):

  • قيود المضيف: إذا كانت سياسة المؤسسة ExtensionSettings تحدّد المضيفين المحظورين (runtime_blocked_hosts) لإحدى الإضافات، سيتم حظر browser.debugger.attach() على جميع الأهداف مع ظهور الخطأ "Host access is restricted by policy." (حتى إذا كانت المصادر الفردية في runtime_allowed_hosts).
  • سياسات أخذ لقطات الشاشة ومنع فقدان البيانات: إذا كانت سياسة المؤسسة DisableScreenshots تمنع أخذ لقطات الشاشة أو إذا تم تطبيق قواعد منع فقدان البيانات على الهدف، ستتعذّر عملية browser.debugger.attach() وسيظهر الخطأ "Screenshot capture is restricted by policy.".

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

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

الأهداف

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

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

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

لأسباب تتعلق بالأمان، لا تتيح واجهة برمجة التطبيقات browser.debugger الوصول إلى جميع نطاقات بروتوكول Chrome DevTools. النطاقات المتاحة هي: Accessibility وAudits وCacheStorage وConsole وCSS وDatabase وDebugger وDOM وDOMDebugger وDOMSnapshot وEmulation وFetch وIO وInput وInspector وLog وNetwork وOverlay وPage وPerformance وRuntime وStorage وTarget وTracing وWebAudio وWebAuthn.

العمل على الإطارات

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

لإرفاق جميع الإطارات، عليك التعامل مع كل نوع من الإطارات بشكل منفصل:

  • استمِع إلى الحدث Runtime.executionContextCreated لتحديد سياقات التنفيذ الجديدة المرتبطة بإطارات العملية نفسها.

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

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

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

لإرفاق إطار فرعي خارج العملية تلقائيًا، عليك أولاً إضافة أداة معالجة للحدث Target.attachedToTarget:

browser.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 browser.debugger.sendCommand(session, "Runtime.enable");
  }
});

بعد ذلك، فعِّل خيار المرفقات التلقائية عن طريق إرسال الأمر Target.setAutoAttach مع ضبط الخيار flatten على true:

await browser.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 والإصدارات الأحدث

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

تعداد

"target_closed"

"canceled_by_user"

TargetInfo

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

الخصائص

  • مرفق

    قيمة منطقية

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

  • extensionId

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

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

  • faviconUrl

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

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

  • id

    سلسلة

    معرّف الاستهداف

  • tabId

    number اختياري

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

  • title

    سلسلة

    تمثّل هذه السمة عنوان الصفحة المستهدَفة.

  • النوع

    TargetInfoType

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

  • url

    سلسلة

    عنوان URL المستهدَف

TargetInfoType

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

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

تعداد

"page"

"background_page"

"worker"

"other"

الطُرق

attach()

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

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

المعلمات

  • target

    Debuggee

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

  • requiredVersion

    سلسلة

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

المرتجعات

  • Promise<void>

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

    يتم حلّها عند نجاح عملية الربط أو تعذّرها. يتم تنفيذ الوعد بدون قيمة. إذا تعذّر الربط، سيتم رفض الوعد.

detach()

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

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

المعلمات

  • target

    Debuggee

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

المرتجعات

  • Promise<void>

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

    يتم حلّها عند نجاح عملية الفصل أو تعذّرها. يتم تنفيذ الوعد بدون قيمة. إذا تعذّر فصل الحساب، سيتم رفض الوعد.

getTargets()

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

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

المرتجعات

  • Promise<TargetInfo[]>

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

sendCommand()

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

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

المعلمات

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

  • method

    سلسلة

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

  • commandParams

    كائن اختياري

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

المرتجعات

  • Promise<object | undefined>

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

    نص الرد إذا حدث خطأ أثناء نشر الرسالة، سيتم رفض الوعد.

الفعاليات

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

      سلسلة

    • المَعلمات

      كائن اختياري