chrome.devtools.inspectedWindow

الوصف

استخدام واجهة برمجة التطبيقات chrome.devtools.inspectedWindow للتفاعل مع النافذة التي تم فحصها: احصل على رقم تعريف علامة التبويب للصفحة التي تم فحصها، أو قيِّم الرمز في سياق النافذة التي تم فحصها، أو أعِد تحميل الصفحة، أو احصل على قائمة الموارد داخل الصفحة.

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

توفّر السمة tabId معرّف علامة التبويب الذي يمكنك استخدامه مع طلبات البيانات من واجهة برمجة التطبيقات في chrome.tabs.*. مع ذلك، يُرجى العِلم أنّ chrome.tabs.* API لا تظهر لصفحات إضافات أدوات المطوّرين بسبب اعتبارات أمنية، وسيكون عليك تمرير رقم تعريف علامة التبويب إلى صفحة الخلفية واستدعاء دوال chrome.tabs.* API من هناك.

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

استخدِم الطلب getResources والحدث onResourceContent للحصول على قائمة بالموارد (المستندات وأوراق الأنماط والنصوص البرمجية والصور وغيرها) ضمن الصفحة التي تم فحصها. يمكن استخدام الطريقتَين getContent وsetContent للفئة Resource إلى جانب الحدث onResourceContentCommitted لإتاحة تعديل محتوى المورد، على سبيل المثال، من خلال محرّر خارجي.

البيان

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

"devtools_page"

تنفيذ التعليمة البرمجية في النافذة التي تم فحصها

تتيح الطريقة 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,
)

لاسترداد قائمة الموارد من الصفحة التي تم فحصها.

المَعلمات

  • معاودة الاتصال

    الوظيفة

    تبدو معلَمة callback على النحو التالي: 

    (resources: Resource[])=>void

    • المراجع

      المصدر[]

      الموارد ضمن الصفحة.

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,
)

يتم تنشيطها عند الالتزام بنسخة جديدة من المورد (مثلاً، يحفظ المستخدم نسخة معدَّلة من المورد في "أدوات المطوّرين").

المَعلمات

  • معاودة الاتصال

    الوظيفة

    تبدو معلَمة callback على النحو التالي: 

    (resource: Resource,content: string)=>void