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 توقف التقاط لقطات الشاشة أو كانت قواعد منع فقدان البيانات (DLP) تنطبق على الهدف، يتعذّر تنفيذ browser.debugger.attach() مع ظهور الخطأ "Screenshot capture is restricted by policy.".

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

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

الأهداف

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

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

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

لأسباب تتعلق بالأمان، لا تتيح واجهة برمجة التطبيقات browser.debugger الوصول إلى جميع نطاقات بروتوكول أدوات مطوّري البرامج في Chrome. النطاقات المتاحة هي: أدوات تسهيل الاستخدام وعمليات التدقيق وCacheStorage ووحدة التحكّم وCSS وقاعدة البيانات وبرنامج تصحيح الأخطاء وDOM وDOMDebugger وDOMSnapshot والمحاكاة والجلب والإدخال/الإخراج والإدخال وأداة الفحص والسجلّ والشبكة والتراكب والصفحة والأداء ووقت التشغيل ومساحة التخزين والهدف والتتبّع و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 لكي يربط B الجلسة بـ C.

أمثلة

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

الأنواع

Debuggee

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

الخصائص

  • extensionId

    string اختياري

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

  • tabId

    number اختيارية

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

  • targetId

    string اختياري

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

DebuggerSession

الإصدار 125 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

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

الخصائص

  • extensionId

    string اختياري

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

  • sessionId

    string اختياري

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

  • tabId

    number اختيارية

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

  • targetId

    string اختياري

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

DetachReason

الإصدار 44 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

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

Enum

"target_closed"

"canceled_by_user"

TargetInfo

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

الخصائص

  • متصل

    قيمة منطقية

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

  • extensionId

    string اختياري

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

  • faviconUrl

    string اختياري

    عنوان URL المستهدَف للرمز المفضّل

  • id

    سلسلة

    رقم تعريف الهدف

  • tabId

    number اختيارية

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

  • title

    سلسلة

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

  • النوع

    TargetInfoType

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

  • url

    سلسلة

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

TargetInfoType

الإصدار 44 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

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

Enum

"page"

"background_page"

"worker"

"other"

الطُرق

attach()

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

لإرفاق مصحِّح الأخطاء بالهدف المحدّد

المعلمات

  • target

    Debuggee

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

  • requiredVersion

    سلسلة

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

المرتجعات

  • وعد<فراغ>

    الإصدار 96 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

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

detach()

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

لفصل مصحِّح الأخطاء عن الهدف المحدّد

المعلمات

  • target

    Debuggee

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

المرتجعات

  • وعد<فراغ>

    الإصدار 96 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

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

getTargets()

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

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

المرتجعات

  • Promise<TargetInfo[]>

    الإصدار 96 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

sendCommand()

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

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

المعلمات

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

  • method

    سلسلة

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

  • commandParams

    object اختياري

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

المرتجعات

  • Promise<object | undefined>

    الإصدار 96 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

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

الفعاليات

onDetach

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

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

المعلمات

onEvent

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

يتم تشغيله عند تصحيح أخطاء حدث قياس مشاكل الاستهداف.

المعلمات

  • callback

    دالة

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

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

    • المصدر

      DebuggerSession

    • method

      سلسلة

    • params

      object اختياري