chrome.debugger

الوصف

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

الأذونات

debugger

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

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

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

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

الأهداف

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

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

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

لأسباب تتعلّق بالأمان، لا توفّر واجهة برمجة التطبيقات chrome.debugger إمكانية الوصول إلى جميع نطاقات البروتوكولات الأساسية في أدوات مطوّري البرامج في Chrome. النطاقات المتاحة هي: Accessibility (تسهيل الاستخدام) والتدقيق وCacheStorage وConsole وCSS وDatabase وDebugger وDOM DOMDebugger وDOMSnapshotWebAudioWebAuthn

استخدام الإطارات

لا يوجد تعيين واحد لواحد للإطارات بالأهداف. ضمن علامة تبويب واحدة، قد تشترك عدة إطارات للعمليات نفسها في الهدف نفسه، ولكنها تستخدم سياق تنفيذ مختلفًا. من ناحية أخرى، قد يتم إنشاء هدف جديد لإطار 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 }]
});

أمثلة

لتجربة واجهة برمجة التطبيقات هذه، عليك تثبيت مثال واجهة برمجة التطبيقات Debugger API من مستودع chrome-extension-pattern.

الأنواع

Debuggee

معرّف تصحيح الأخطاء يجب تحديد إما TabId أو additionalId أو targetId.

أماكن إقامة

  • extensionId

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

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

  • tabId

    الرقم اختياري

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

  • targetId

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

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

DebuggerSession

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

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

أماكن إقامة

  • extensionId

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

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

  • sessionId

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

    رقم التعريف المبهَم لجلسة بروتوكول أدوات مطوّري البرامج في Chrome. لتحديد جلسة فرعية ضمن جلسة الجذر المحدّدة من خلال tabId أو additionalId أو targetId.

  • tabId

    الرقم اختياري

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

  • targetId

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

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

DetachReason

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

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

التعداد

"target_closed"

"canceled_by_user"

TargetInfo

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

أماكن إقامة

  • مرفق

    boolean

    صحيح إذا سبق إرفاق برنامج تصحيح الأخطاء.

  • extensionId

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

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

  • faviconUrl

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

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

  • id

    سلسلة

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

  • tabId

    الرقم اختياري

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

  • title

    سلسلة

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

  • كتابة

    TargetInfoType

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

  • url

    سلسلة

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

TargetInfoType

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

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

التعداد

"background_page"

الطُرق

attach()

وعد 
chrome.debugger.attach(
  target: Debuggee,
  requiredVersion: string,
  callback?: function,
)

إرفاق برنامج تصحيح الأخطاء بالهدف المحدّد.

المَعلمات

  • الاستهداف

    تصحيح الأخطاء

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

  • requiredVersion

    سلسلة

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

  • معاودة الاتصال

    الدالة اختيارية

    تبدو معلَمة callback على النحو التالي: 

    ()=>void

المرتجعات

  • Promise<void>

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

    تتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.

detach()

وعد 
chrome.debugger.detach(
  target: Debuggee,
  callback?: function,
)

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

المَعلمات

  • الاستهداف

    تصحيح الأخطاء

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

  • معاودة الاتصال

    الدالة اختيارية

    تبدو معلَمة callback على النحو التالي: 

    ()=>void

المرتجعات

  • Promise<void>

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

    تتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.

getTargets()

وعد 
chrome.debugger.getTargets(
  callback?: function,
)

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

المَعلمات

  • معاودة الاتصال

    الدالة اختيارية

    تبدو معلَمة callback على النحو التالي: 

    (result: TargetInfo[])=>void

    • نتيجة

      TargetInfo[]

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

المرتجعات

  • Promise<TargetInfo[]>

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

    تتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.

sendCommand()

وعد 
chrome.debugger.sendCommand(
  target: DebuggerSession,
  method: string,
  commandParams?: object,
  callback?: function,
)

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

المَعلمات

  • الاستهداف

    DebuggerSession

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

  • method

    سلسلة

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

  • commandParams

    الكائن اختياري

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

  • معاودة الاتصال

    الدالة اختيارية

    تبدو معلَمة callback على النحو التالي: 

    (result?: object)=>void

    • نتيجة

      الكائن اختياري

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

المرتجعات

  • Promise<object|undefined>

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

    تتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.

فعاليات

onDetach

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

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

المَعلمات

onEvent

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

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

المَعلمات

  • معاودة الاتصال

    الوظيفة

    تبدو معلَمة callback على النحو التالي: 

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

    • المصدر

      DebuggerSession

    • method

      سلسلة

    • params

      الكائن اختياري