chrome.debugger

الوصف

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

الأذونات

debugger

ملاحظة أمان

لأسباب أمنية، لا تتيح واجهة برمجة التطبيقات 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.

البيان

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

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

أمثلة

لتجربة واجهة برمجة التطبيقات هذه، ثبِّت مثال واجهة برمجة التطبيقات الخاصة بأداة تصحيح الأخطاء من مستودع 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,
  callback?: function,
): Promise<void>

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

المعلمات

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

  • requiredVersion

    سلسلة

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

  • callback

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

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

    () => void

المرتجعات

  • Promise<void>

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

    لا تتوافق الوعود إلا مع الإصدار Manifest V3 والإصدارات الأحدث، ويجب أن تستخدم المنصات الأخرى عمليات رد الاتصال.

detach()

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

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

المعلمات

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

  • callback

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

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

    () => void

المرتجعات

  • Promise<void>

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

    لا تتوافق الوعود إلا مع الإصدار Manifest V3 والإصدارات الأحدث، ويجب أن تستخدم المنصات الأخرى عمليات رد الاتصال.

getTargets()

الوعد 
chrome.debugger.getTargets(
  callback?: function,
): Promise<TargetInfo[]>

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

المعلمات

  • 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,
): Promise<object | undefined>

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

المعلمات

  • الاستهداف

    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

      سلسلة

    • المَعلمات

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