chrome.debugger

الوصف

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

الأذونات

debugger

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

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

قيود سياسات المؤسسة

في أجهزة المؤسسات، قد تقيّد بعض السياسات إمكانية ربط الملحقات بمصحح الأخطاء باستخدام نموذج الكل أو لا شيء عند وقت الربط (chrome.debugger.attach() ):

  • قيود الاستضافة: إذا كانت سياسة المؤسسةExtensionSettings يقوم بتكوين المضيفين المحظورين (runtime_blocked_hosts ) للحصول على تمديد،chrome.debugger.attach() تم حظره على جميع الأهداف مع ظهور الخطأ"Host access is restricted by policy." (حتى لو كانت الأصول الفردية فيruntime_allowed_hosts ).
  • سياسات لقطات الشاشة ومنع فقدان البيانات: إذا كانت سياسة المؤسسةDisableScreenshots يؤدي تعطيل خاصية التقاط لقطات الشاشة أو تطبيق قواعد منع فقدان البيانات (DLP) على الهدف،chrome.debugger.attach() يفشل مع ظهور الخطأ"Screenshot capture is restricted by policy.".

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

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

الأهداف

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

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

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

لأسباب أمنية، لا توفر واجهة برمجة التطبيقات chrome.debugger إمكانية الوصول إلى جميع نطاقات بروتوكول أدوات مطوري Chrome. النطاقات المتاحة هي: إمكانية الوصول ،عمليات التدقيق ،CacheStorage ،وحدة التحكم ،CSS ،قاعدة البيانات ،مصحح الأخطاء ،DOM ،DOMDebugger ،DOMSnapshot ،المحاكاة ،أحضر ،IO ،مدخل ،مفتش ،سجل ،شبكة ،طبقة ،صفحة ،أداء ،محلل الملفات الشخصية ،وقت التشغيل ،تخزين ،هدف ،التتبع ،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");
  }
});

ثم قم بتمكين auto attach عن طريق إرسال الأمر Target.setAutoAttach مع تعيين الخيار flatten إلى true:

await chrome.debugger.sendCommand({ tabId }, "Target.setAutoAttach", {
  autoAttach: true,
  waitForDebuggerOnStart: false,
  flatten: true,
  filter: [{ type: "iframe", exclude: false }]
});

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

أمثلة

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

الأنواع

Debuggee

معرف الهدف من التصحيح. يجب تحديد إما tabId أو extensionId أو targetId

الخصائص

  • extensionId

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

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

  • tabId

    number اختياري

    معرف علامة التبويب التي تنوي تصحيحها.

  • targetId

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

    المعرف المبهم لهدف التصحيح.

DebuggerSession

Chrome 125+

معرّف جلسة تصحيح الأخطاء. يجب تحديد أحد الخيارات التالية: tabId أو extensionId أو targetId. بالإضافة إلى ذلك، يمكن توفير معرف جلسة اختياري. إذا تم تحديد 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,
): Promise<void>

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

المعلمات

  • target

    Debuggee

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

  • requiredVersion

    سلسلة

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

المرتجعات

  • Promise<void>

    Chrome 96+

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

detach()

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

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

المعلمات

  • target

    Debuggee

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

المرتجعات

  • Promise<void>

    Chrome 96+

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

getTargets()

chrome.debugger.getTargets(): Promise<TargetInfo[]>

يُعيد قائمة أهداف التصحيح المتاحة.

المرتجعات

sendCommand()

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

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

المعلمات

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

  • method

    سلسلة

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

  • commandParams

    كائن اختياري

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

المرتجعات

  • وعد<كائن | غير محدد>

    Chrome 96+

    نص الرد. إذا حدث خطأ أثناء إرسال الرسالة، فسيتم رفض الوعد.

الفعاليات

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

      سلسلة

    • المعلمات

      كائن اختياري