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

البيان

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

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

أمثلة

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

الأنواع

Debuggee

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

الخصائص

  • extensionId

    string اختياري

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

  • tabId

    number اختيارية

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

  • targetId

    string اختياري

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

DebuggerSession

الإصدار 125 من 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 أو الإصدارات الأحدث

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

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 أو الإصدارات الأحدث

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

Enum

"page"

"background_page"

"worker"

"other"

الطُرق

attach()

Promise 
chrome.debugger.attach(
  target: Debuggee,
  requiredVersion: string,
  callback?: function,
): Promise<void>

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

المعلمات

  • target

    Debuggee

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

  • requiredVersion

    سلسلة

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

  • callback

    function اختياري

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

    () => void

المرتجعات

  • وعد<فراغ>

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

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

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

detach()

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

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

المعلمات

  • target

    Debuggee

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

  • callback

    function اختياري

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

    () => void

المرتجعات

  • وعد<فراغ>

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

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

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

getTargets()

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

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

المعلمات

  • callback

    function اختياري

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

    (result: TargetInfo[]) => void

    • نتيجة

      TargetInfo[]

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

المرتجعات

  • Promise<TargetInfo[]>

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

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

sendCommand()

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

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

المعلمات

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

  • method

    سلسلة

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

  • commandParams

    object اختياري

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

  • callback

    function اختياري

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

    (result?: object) => void

    • نتيجة

      object اختياري

      كائن 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

      object اختياري