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، يمكنك الاطّلاع على المستندات الرسمية حول 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، الأداء، 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 }]
});

لا يتمّ إرفاق الإطارات تلقائيًا إلا بالإطارات التي يعرفها الهدف، والتي تقتصر على الإطارات الفرعية المباشرة لإطار مرتبط به. على سبيل المثال، مع التسلسل الهرمي للإطارات أ -> ب -> ج (حيث تكون جميعها من مصادر مختلفة)، سيؤدي استدعاء Target.setAutoAttach للهدف المرتبط بالإطار أ إلى إرفاق الجلسة أيضًا بالإطار ب. ومع ذلك، هذه العملية ليست متكرّرة، لذا يجب أيضًا استدعاء Target.setAutoAttach لكي يتمكّن "ب" من إرفاق الجلسة بـ "ج".

أمثلة

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

الأنواع

Debuggee

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

الخصائص

  • extensionId

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

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

  • tabId

    رقم اختياري

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

  • targetId

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

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

DebuggerSession

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

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

الخصائص

  • extensionId

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

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

  • sessionId

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

    المعرّف غير الواضح لجلسة Chrome DevTools Protocol لتحديد جلسة فرعية ضمن الجلسة الجذر التي تم تحديدها من خلال tabId أو extensionId أو targetId

  • tabId

    رقم اختياري

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

  • targetId

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

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

DetachReason

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

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

Enum

"target_closed"

"canceled_by_user"

TargetInfo

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

الخصائص

  • مرفق

    قيمة منطقية

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

  • extensionId

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

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

  • faviconUrl

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

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

  • id

    سلسلة

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

  • tabId

    رقم اختياري

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

  • title

    سلسلة

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

  • كتابة

    TargetInfoType

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

  • url

    سلسلة

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

TargetInfoType

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

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

Enum

"page"

"background_page"

"worker"

"other"

الطُرق

attach()

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

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

المعلمات

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

  • requiredVersion

    سلسلة

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

  • callback

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

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

    () => void

المرتجعات

  • Promise<void>

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

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

detach()

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

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

المعلمات

المرتجعات

  • Promise<void>

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

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

getTargets()

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

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

المعلمات

  • callback

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

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

    (result: TargetInfo[]) => void

    • نتيجة

      TargetInfo[]

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

المرتجعات

  • Promise<TargetInfo[]>

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

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

sendCommand()

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

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

المعلمات

  • الاستهداف

    DebuggerSession

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

  • method

    سلسلة

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

  • commandParams

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

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

  • callback

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

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

    (result?: object) => void

    • نتيجة

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

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

المرتجعات

  • Promise<object | undefined>

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

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

الفعاليات

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

      سلسلة

    • params

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