الوصف
استخدام واجهة برمجة التطبيقات chrome.devtools.inspectedWindow
للتفاعل مع النافذة التي تم فحصها: احصل على رقم تعريف علامة التبويب للصفحة التي تم فحصها، أو قيِّم الرمز في سياق النافذة التي تم فحصها، أو أعِد تحميل الصفحة، أو احصل على قائمة الموارد داخل الصفحة.
البيان
يجب الإعلان عن المفاتيح التالية في ملف البيان كي تتمكّن من استخدام واجهة برمجة التطبيقات هذه.
"devtools_page"
استخدِم chrome.devtools.inspectedWindow
للتفاعل مع النافذة التي تم فحصها: احصل على رقم تعريف علامة التبويب للصفحة التي تم فحصها، أو قيِّم الرمز في سياق النافذة التي تم فحصها، أو أعِد تحميل الصفحة، أو احصل على قائمة الموارد داخل الصفحة.
يمكنك الاطّلاع على ملخّص عن واجهات برمجة التطبيقات في أدوات مطوّري البرامج للحصول على مقدمة عامة عن استخدام واجهات برمجة التطبيقات الخاصة بـ "أدوات مطوّري البرامج".
نظرة عامة
توفّر السمة tabId
معرّف علامة التبويب الذي يمكنك استخدامه مع طلبات البيانات من واجهة برمجة التطبيقات في chrome.tabs.*
. مع ذلك، يُرجى العِلم أنّ chrome.tabs.*
API لا تظهر لصفحات إضافات أدوات المطوّرين بسبب اعتبارات أمنية، وسيكون عليك تمرير رقم تعريف علامة التبويب إلى صفحة الخلفية واستدعاء دوال chrome.tabs.*
API من هناك.
يمكن استخدام الطريقة reload
لإعادة تحميل الصفحة التي تم فحصها. بالإضافة إلى ذلك، يمكن للطالب تحديد تجاوز لسلسلة وكيل المستخدم، أو نص برمجي سيتم إدخاله مبكرًا عند تحميل الصفحة، أو خيار لفرض إعادة تحميل الموارد المخزّنة مؤقتًا.
استخدِم الطلب getResources
والحدث onResourceContent
للحصول على قائمة بالموارد
(المستندات وأوراق الأنماط والنصوص البرمجية والصور وغيرها) ضمن الصفحة التي تم فحصها. يمكن استخدام الطريقتَين getContent
وsetContent
للفئة Resource
إلى جانب الحدث onResourceContentCommitted
لإتاحة تعديل محتوى المورد، على سبيل المثال، من خلال محرّر خارجي.
تنفيذ التعليمة البرمجية في النافذة المفحصة
تتيح الطريقة eval
للإضافات إمكانية تنفيذ رمز JavaScript في سياق الصفحة التي تم فحصها. تُعدّ هذه الطريقة فعّالة عند استخدامها في السياق الصحيح وتكون خطيرة عند استخدامها بشكل غير ملائم. استخدِم الإجراء tabs.executeScript
ما لم تكن بحاجة إلى الوظائف المحدّدة التي توفّرها طريقة eval
.
في ما يلي الاختلافات الرئيسية بين eval
وtabs.executeScript
:
- لا تستخدم الطريقة
eval
عالمًا معزولاً للرمز الذي يتم تقييمه، وبالتالي يمكن للرمز الوصول إلى حالة JavaScript للنافذة التي تم فحصها. استخدِم هذه الطريقة عندما يكون الوصول إلى حالة JavaScript مطلوبًا للصفحة التي تم فحصها. - يتضمّن سياق تنفيذ الرمز البرمجي الذي يتم تقييمه واجهة برمجة التطبيقات لوحدة تحكُّم أدوات المطوّرين.
على سبيل المثال، يمكن أن يستخدم الرمز
inspect
و$0
. - قد يعرض الرمز الذي تم تقييمه قيمة تم تمريرها إلى معاودة الاتصال بالإضافة. يجب أن تكون القيمة التي تم إرجاعها كائن JSON صالحًا (قد تحتوي فقط على أنواع JavaScript أساسية ومراجع دورية إلى كائنات JSON أخرى). يُرجى توخي الحذر الشديد أثناء معالجة البيانات المُستلَمة من الصفحة التي تم فحصها، إذ يتم التحكّم في سياق التنفيذ بشكل أساسي من خلال الصفحة التي تم فحصها، وقد تؤثر الصفحة الضارة في البيانات التي يتم عرضها في الإضافة.
تجدر الإشارة إلى أنّه يمكن أن تتضمّن الصفحة سياقات مختلفة لتنفيذ JavaScript. ولكل إطار سياقه الخاص، بالإضافة إلى سياق إضافي لكل إضافة تتضمن نصوصًا برمجية للمحتوى تعمل في هذا الإطار.
يتم تنفيذ الطريقة eval
تلقائيًا في سياق الإطار الرئيسي للصفحة التي تم فحصها.
تستخدم الطريقة eval
وسيطة اختيارية ثانية يمكنك استخدامها لتحديد السياق الذي يتم تقييم الرمز فيه. يمكن أن يحتوي كائن options هذا على مفتاح واحد أو أكثر من المفاتيح التالية:
frameURL
- استخدِم هذه السمة لتحديد إطار غير الإطار الرئيسي للصفحة التي تم فحصها.
contextSecurityOrigin
- استخدِم هذه الميزة لاختيار سياق ضمن الإطار المحدّد وفقًا لمصدر الويب.
useContentScriptContext
- في حال اختيار القيمة "صحيح"، يمكنك تنفيذ النص البرمجي في سياق النصوص البرمجية للمحتوى للإضافات. (بما يعادل تحديد مؤسسة الويب للإضافات على أنها مصدر أمان السياق). يمكن استخدام ذلك لتبادل البيانات مع النص البرمجي للمحتوى.
أمثلة
تتحقق الرموز التالية من إصدار jQuery الذي تستخدمه الصفحة التي تم فحصها:
chrome.devtools.inspectedWindow.eval(
"jQuery.fn.jquery",
function(result, isException) {
if (isException) {
console.log("the page is not using jQuery");
} else {
console.log("The page is using jQuery v" + result);
}
}
);
لتجربة واجهة برمجة التطبيقات هذه، يمكنك تثبيت أمثلة على devtools API من مستودع chrome-extension-pattern.
الأنواع
Resource
مورد ضمن الصفحة التي تم فحصها، مثل مستند أو نص برمجي أو صورة
أماكن إقامة
-
url
سلسلة
عنوان URL للمصدر.
-
getContent
void
الحصول على محتوى المورد.
تبدو الدالة
getContent
على النحو التالي:(callback: function) => {...}
-
معاودة الاتصال
الوظيفة
تبدو معلَمة
callback
على النحو التالي:(content: string, encoding: string) => void
-
بمحتوى
سلسلة
محتوى المورد (من المحتمل أن يكون مشفّرًا).
-
الترميز
سلسلة
هذا الحقل فارغًا إذا لم يتم ترميز المحتوى، وسيتم ترميز اسم الترميز بطريقة أخرى. في الوقت الحالي، لا يمكن استخدام سوى base64.
-
-
-
setContent
void
لتعيين محتوى المورد.
تبدو الدالة
setContent
على النحو التالي:(content: string, commit: boolean, callback?: function) => {...}
-
بمحتوى
سلسلة
محتوى جديد للمصدر. لا تتوافق حاليًا سوى الموارد ذات نوع النص.
-
الإتمام
boolean
صحيح إذا انتهى المستخدم من تعديل المورد، ويجب أن يستمر المحتوى الجديد للمورّد، أو خطأ إذا كان هذا تغييرًا ثانويًا يتم إرساله أثناء تعديل المستخدم للمورد.
-
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
callback
على النحو التالي:(error?: object) => void
-
خطأ
الكائن اختياري
يتم الضبط على "غير محدّد" إذا تم ضبط محتوى المورد بنجاح، ويصف الخطأ بخلاف ذلك.
-
-
أماكن إقامة
tabId
رقم تعريف علامة التبويب التي يتم فحصها. يمكن استخدام هذا المعرّف مع chrome.tabs.* API.
النوع
الرقم
الطُرق
eval()
chrome.devtools.inspectedWindow.eval(
expression: string,
options?: object,
callback?: function,
)
تقيِّم هذه السمة تعبير JavaScript في سياق الإطار الرئيسي للصفحة التي تم فحصها. يجب تقييم التعبير إلى كائن متوافق مع JSON، وإلّا يتم تطبيق استثناء. يمكن لدالة التقييم الإبلاغ عن خطأ من جانب "أدوات مطوّري البرامج" أو استثناء JavaScript يحدث أثناء التقييم. في كلتا الحالتين، فإن معلمة result
لمعاودة الاتصال هي undefined
. في حال حدوث خطأ من جهة مطوّري البرامج، تكون المَعلمة isException
غير فارغة وتم ضبط isError
على "صحيح" وضبط code
على رمز خطأ. في حال حدوث خطأ في JavaScript، يتم ضبط isException
على "صحيح" وضبط value
على قيمة سلسلة الكائن المُستغرَق.
المَعلمات
-
تعبير
سلسلة
تعبير مطلوب تقييمه.
-
الخيارات
الكائن اختياري
ويمكن أن تحتوي مَعلمة الخيارات على خيار واحد أو أكثر.
-
frameURL
سلسلة اختيارية
وإذا تم تحديد التعبير، يتم تقييمه على إطار iframe الذي يتطابق عنوان URL الخاص به مع العنوان المحدّد. يتم تقييم التعبير تلقائيًا في الإطار العلوي من الصفحة التي تم فحصها.
-
scriptExecutionContext
سلسلة اختيارية
Chrome 107 والإصدارات الأحدثويمكنك تقييم التعبير في سياق نص برمجي لإضافة تتطابق مع المصدر المحدّد. في حال توفيره، يلغي ScriptExecutionContext الإعداد "true" في useContentScriptContext.
-
useContentScriptContext
منطقية اختيارية
قيِّم التعبير في سياق النص البرمجي لمحتوى إضافة الاستدعاء، بشرط أن يكون قد تم إدخال النص البرمجي للمحتوى مسبقًا في الصفحة التي تم فحصها. وإذا لم يكن الأمر كذلك، لا يتم تقييم التعبير ويتم استدعاء معاودة الاتصال مع ضبط معلَمة الاستثناء على عنصر تم ضبط الحقل
isError
على "صحيح" وضبط الحقلcode
علىE_NOTFOUND
.
-
-
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
callback
على النحو التالي:(result: object, exceptionInfo: object) => void
-
نتيجة
كائن
نتيجة التقييم.
-
exceptionInfo
كائن
عنصر يقدّم تفاصيل في حال حدوث استثناء أثناء تقييم التعبير.
-
رمز
سلسلة
يمكنك تحديد ما إذا كان الخطأ قد حدث من جانب "أدوات مطوري البرامج" قبل تقييم التعبير.
-
الوصف
سلسلة
يمكنك تحديد ما إذا كان الخطأ قد حدث من جانب "أدوات مطوري البرامج" قبل تقييم التعبير.
-
التفاصيل
أي[]
حدِّد هذا الحقل إذا كان الخطأ قد حدث من جهة أدوات مطوّري البرامج قبل تقييم التعبير، ويحتوي على مصفوفة القيم التي يمكن استبدالها في سلسلة الوصف لتوفير مزيد من المعلومات حول سبب الخطأ.
-
isError
boolean
يمكنك تحديد ما إذا كان الخطأ قد حدث من جانب "أدوات مطوري البرامج" قبل تقييم التعبير.
-
isException
boolean
يتم تحديد ما إذا كان الرمز البرمجي الذي تم تقييمه يمثِّل استثناءً لم تتم معالجته.
-
القيمة
سلسلة
يتم تحديد ما إذا كان الرمز البرمجي الذي تم تقييمه يمثِّل استثناءً لم تتم معالجته.
-
-
getResources()
chrome.devtools.inspectedWindow.getResources(
callback: function,
)
لاسترداد قائمة الموارد من الصفحة التي تم فحصها.
المَعلمات
reload()
chrome.devtools.inspectedWindow.reload(
reloadOptions?: object,
)
لإعادة تحميل الصفحة التي تم فحصها
المَعلمات
-
reloadOptions
الكائن اختياري
-
ignoreCache
منطقية اختيارية
عند ضبط القيمة على "صحيح"، سيتجاوز برنامج التحميل ذاكرة التخزين المؤقت لجميع موارد الصفحة التي تم فحصها والتي تم تحميلها قبل تنشيط حدث
load
. يشبه التأثير الضغط على Ctrl+Shift+R في النافذة التي تم فحصها أو داخل نافذة أدوات المطور. -
injectedScript
سلسلة اختيارية
وفي حال تحديد ذلك، سيتم إدخال النص البرمجي في كل إطار من الصفحة التي تم فحصها فور التحميل، وقبل أي من النصوص البرمجية للإطار. لن يتم إدخال النص البرمجي بعد عمليات إعادة التحميل اللاحقة، مثلاً إذا ضغط المستخدم على Ctrl+R.
-
userAgent
سلسلة اختيارية
وفي حال تحديد هذه السياسة، ستلغي السلسلة قيمة عنوان HTTP
User-Agent
التي يتم إرسالها أثناء تحميل موارد الصفحة التي تم فحصها. وستلغي السلسلة أيضًا قيمة السمةnavigator.userAgent
التي يتم عرضها على أي نصوص برمجية يتم تشغيلها في الصفحة التي تم فحصها.
-
فعاليات
onResourceAdded
chrome.devtools.inspectedWindow.onResourceAdded.addListener(
callback: function,
)
يتم تنشيطها عند إضافة مورد جديد إلى الصفحة التي تم فحصها.
المَعلمات
-
معاودة الاتصال
الوظيفة
تبدو معلَمة
callback
على النحو التالي:(resource: Resource) => void
-
المصدر
-
onResourceContentCommitted
chrome.devtools.inspectedWindow.onResourceContentCommitted.addListener(
callback: function,
)
يتم تنشيطها عند الالتزام بنسخة جديدة من المورد (مثلاً، يحفظ المستخدم نسخة معدَّلة من المورد في "أدوات المطوّرين").