الوصف
تعمل واجهة برمجة التطبيقات 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. النطاقات المتاحة هي: Accessibility (تسهيل الاستخدام)
والتدقيق وCacheStorage وConsole
وCSS وDatabase وDebugger وDOM
DOMDebugger وDOMSnapshotWebAudioWebAuthn
استخدام الإطارات
لا يوجد تعيين واحد لواحد للإطارات بالأهداف. ضمن علامة تبويب واحدة، قد تشترك عدة إطارات للعمليات نفسها في الهدف نفسه، ولكنها تستخدم سياق تنفيذ مختلفًا. من ناحية أخرى، قد يتم إنشاء هدف جديد لإطار 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 }]
});
أمثلة
لتجربة واجهة برمجة التطبيقات هذه، عليك تثبيت مثال واجهة برمجة التطبيقات Debugger API من مستودع chrome-extension-pattern.
الأنواع
Debuggee
معرّف تصحيح الأخطاء يجب تحديد إما TabId أو additionalId أو targetId.
أماكن إقامة
-
extensionId
سلسلة اختيارية
رقم تعريف الإضافة التي تريد تصحيح أخطائها. لا يمكن إرفاق صفحة خلفية لإحدى الإضافات إلا عند استخدام مفتاح سطر أوامر
--silent-debugger-extension-api
. -
tabId
الرقم اختياري
رقم تعريف علامة التبويب التي تريد تصحيح أخطائها
-
targetId
سلسلة اختيارية
رقم التعريف المبهَم لهدف تصحيح الأخطاء.
DebuggerSession
معرّف جلسة برنامج تصحيح الأخطاء. يجب تحديد واحد من tabId أو additionalId أو targetId. بالإضافة إلى ذلك، يمكن تقديم sessionId اختياري. إذا تم تحديد sessionId للوسيطات المُرسَلة من onEvent
، يعني ذلك أنّ الحدث يأتي من جلسة بروتوكول فرعية ضمن جلسة تصحيح الأخطاء الجذر. في حال تحديد sessionId عند تمريرها إلى sendCommand
، ستستهدِف جلسة بروتوكول فرعية ضمن جلسة تصحيح الأخطاء الجذر.
أماكن إقامة
-
extensionId
سلسلة اختيارية
رقم تعريف الإضافة التي تريد تصحيح أخطائها. لا يمكن إرفاق صفحة خلفية لإحدى الإضافات إلا عند استخدام مفتاح سطر أوامر
--silent-debugger-extension-api
. -
sessionId
سلسلة اختيارية
رقم التعريف المبهَم لجلسة بروتوكول أدوات مطوّري البرامج في Chrome. لتحديد جلسة فرعية ضمن جلسة الجذر المحدّدة من خلال tabId أو additionalId أو targetId.
-
tabId
الرقم اختياري
رقم تعريف علامة التبويب التي تريد تصحيح أخطائها
-
targetId
سلسلة اختيارية
رقم التعريف المبهَم لهدف تصحيح الأخطاء.
DetachReason
سبب إنهاء الاتصال
التعداد
"target_closed"
"canceled_by_user"
TargetInfo
معلومات تصحيح الأخطاء المستهدفة
أماكن إقامة
-
مرفق
boolean
صحيح إذا سبق إرفاق برنامج تصحيح الأخطاء.
-
extensionId
سلسلة اختيارية
رقم تعريف الإضافة، يتم تحديده إذا كان النوع = 'background_page'.
-
faviconUrl
سلسلة اختيارية
عنوان URL للرمز المفضّل المستهدَف.
-
id
سلسلة
رقم تعريف الهدف.
-
tabId
الرقم اختياري
رقم تعريف علامة التبويب، يتم تحديده إذا كان النوع == 'page'
-
title
سلسلة
عنوان الصفحة المستهدف.
-
كتابة
نوع الاستهداف.
-
url
سلسلة
عنوان URL المستهدف.
TargetInfoType
نوع الاستهداف.
التعداد
"background_page"
الطُرق
attach()
chrome.debugger.attach(
target: Debuggee,
requiredVersion: string,
callback?: function,
)
إرفاق برنامج تصحيح الأخطاء بالهدف المحدّد.
المَعلمات
-
الاستهداف
تصحيح أخطاء الاستهداف الذي تريد إرفاقه
-
requiredVersion
سلسلة
إصدار بروتوكول تصحيح الأخطاء المطلوب ("0.1"). يمكن إرفاق أحدهما فقط بتصحيح الأخطاء الذي يتضمّن رقم إصدار رئيسي مطابق وإصدار ثانوي أكبر أو مساوٍ له. يمكن الحصول على قائمة إصدارات البروتوكول من هنا.
-
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
callback
على النحو التالي:() => void
المرتجعات
-
Promise<void>
Chrome 96 والإصدارات الأحدثتتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.
detach()
chrome.debugger.detach(
target: Debuggee,
callback?: function,
)
لفصل برنامج تصحيح الأخطاء عن الهدف المحدّد.
المَعلمات
-
الاستهداف
تصحيح أخطاء الاستهداف الذي تريد إزالته منه.
-
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
callback
على النحو التالي:() => void
المرتجعات
-
Promise<void>
Chrome 96 والإصدارات الأحدثتتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.
getTargets()
chrome.debugger.getTargets(
callback?: function,
)
تعرض قائمة أهداف تصحيح الأخطاء المتاحة.
المَعلمات
-
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
callback
على النحو التالي:(result: TargetInfo[]) => void
-
نتيجة
مصفوفة من عناصر TargetInfo المقابلة لأهداف تصحيح الأخطاء المتاحة.
-
المرتجعات
-
Promise<TargetInfo[]>
Chrome 96 والإصدارات الأحدثتتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.
sendCommand()
chrome.debugger.sendCommand(
target: DebuggerSession,
method: string,
commandParams?: object,
callback?: function,
)
لإرسال الأمر المعيّن إلى هدف تصحيح الأخطاء
المَعلمات
-
الاستهداف
تصحيح أخطاء الاستهداف الذي تريد إرسال الأمر إليه
-
method
سلسلة
اسم الطريقة. استخدام إحدى الطرق التي يحددها بروتوكول تصحيح الأخطاء عن بُعد.
-
commandParams
الكائن اختياري
كائن JSON مع مَعلمات الطلب يجب أن يتوافق هذا العنصر مع مخطط مَعلمات تصحيح الأخطاء عن بُعد للطريقة المحدّدة.
-
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
callback
على النحو التالي:(result?: object) => void
-
نتيجة
الكائن اختياري
كائن JSON مع الاستجابة. تختلف بنية الاستجابة بناءً على اسم الطريقة ويتم تحديدها من خلال السمة "returns" (إرجاع) لوصف الأمر في بروتوكول تصحيح الأخطاء عن بُعد.
-
المرتجعات
-
Promise<object | undefined>
Chrome 96 والإصدارات الأحدثتتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.
فعاليات
onDetach
chrome.debugger.onDetach.addListener(
callback: function,
)
يتم تنشيطها عند إنهاء المتصفح جلسة تصحيح الأخطاء لعلامة التبويب. ويحدث ذلك عند إغلاق علامة التبويب أو عند استدعاء "أدوات مطوري البرامج في Chrome" لعلامة التبويب المرفقة.
المَعلمات
-
معاودة الاتصال
الوظيفة
تبدو معلَمة
callback
على النحو التالي:(source: Debuggee, reason: DetachReason) => void
-
المصدر
-
السبب
-
onEvent
chrome.debugger.onEvent.addListener(
callback: function,
)
يتم تنشيطها عندما يحدث خطأ عند تصحيح الأخطاء في الأحداث المستهدفة.
المَعلمات
-
معاودة الاتصال
الوظيفة
تبدو معلَمة
callback
على النحو التالي:(source: DebuggerSession, method: string, params?: object) => void
-
المصدر
-
method
سلسلة
-
params
الكائن اختياري
-