chrome.debugger

refresh date: 2026-09-25 robots: noindex

الوصف

تعمل واجهة برمجة التطبيقات 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 والإصدارات الأحدث

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

تعداد

"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,
  callback?: function,
): Promise<void>

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

المعلمات

  • target

    Debuggee

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

  • requiredVersion

    سلسلة

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

  • callback

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

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

    () => void

المرتجعات

  • Promise<void>

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

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

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

detach()

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

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

المعلمات

  • target

    Debuggee

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

  • callback

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

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

    () => void

المرتجعات

  • Promise<void>

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

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

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

getTargets()

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

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

المعلمات

  • callback

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

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

    (result: TargetInfo[]) => void

    • نتيجة

      TargetInfo[]

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

المرتجعات

  • Promise<TargetInfo[]>

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

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

sendCommand()

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

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

المعلمات

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

  • method

    سلسلة

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

  • commandParams

    كائن اختياري

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

  • callback

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

    تظهر المَعلمة 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

    دالة

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

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

    • المصدر

      DebuggerSession

    • method

      سلسلة

    • المَعلمات

      كائن اختياري