chrome.devtools.inspectedWindow

الوصف

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

البيان

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

"devtools_page"

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

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

نظرة عامة

توفّر السمة tabId معرّف علامة التبويب الذي يمكنك استخدامه مع chrome.tabs.*. طلبات بيانات من واجهة برمجة التطبيقات يُرجى العِلم أنّ واجهة برمجة التطبيقات chrome.tabs.* غير خاضعة لأدوات المطوّرين. إضافات الصفحات لاعتبارات تتعلق بالأمان، لذلك ستحتاج إلى تمرير رقم تعريف علامة التبويب إلى الخلفية واستدعاء دوال 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 الأخرى). يُرجى الانتباه بشكل إضافي أثناء معالجة البيانات التي تم تلقّيها. من الصفحة التي تم فحصها - يتم التحكم في سياق التنفيذ بشكل أساسي من خلال الصفحة التي تم فحصها؛ CANNOT TRANSLATE صفحة ضارة في البيانات التي يتم عرضها في الإضافة.

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

يتم تلقائيًا تنفيذ الطريقة eval في سياق الإطار الرئيسي للصفحة التي تم فحصها.

تستخدم طريقة eval وسيطة ثانية اختيارية يمكنك استخدامها لتحديد السياق الذي يتم تقييم التعليمة البرمجية. يمكن أن يحتوي كائن options هذا على مفتاح واحد أو أكثر من المفاتيح التالية:

frameURL
استخدِم هذه السمة لتحديد إطار غير الإطار الرئيسي للصفحة التي تم فحصها.
contextSecurityOrigin
استخدِم هذه السمة لاختيار سياق داخل الإطار المحدّد وفقًا لمصدر الويب الخاص به.
useContentScriptContext
إذا كانت القيمة هي true، يمكنك تنفيذ النص البرمجي في السياق نفسه مثل النصوص البرمجية لمحتوى الإضافات. (تعادل تحديد مؤسسة الويب الخاصة بالإضافات على أنها أصل أمان السياق). يمكن استخدام هذا لتبادل البيانات مع النص البرمجي للمحتوى.

أمثلة

يتحقق الرمز البرمجي التالي من إصدار 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);
    }
  }
);

لتجربة واجهة برمجة التطبيقات هذه، يُرجى تثبيت أمثلة على واجهة برمجة تطبيقات أدوات مطوّري البرامج من chrome-extension-samples المستودع.

الأنواع

Resource

مصدر ضمن الصفحة التي تم فحصها، مثل مستند أو نص برمجي أو صورة

أماكن إقامة

  • url

    سلسلة

    عنوان URL للمصدر.

  • getContent

    فراغ

    الحصول على محتوى المورد.

    تبدو دالة getContent كما يلي: 

    (callback: function) => {...}

    • رد الاتصال

      دالة

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

      (content: string, encoding: string) => void

      • محتوى

        سلسلة

        محتوى المورد (من المحتمل أن يكون مُشفَّرًا).

      • الترميز

        سلسلة

        يكون هذا الحقل فارغًا إذا لم يكن المحتوى مُرمّزًا، أو اسم الترميز غير ذلك. في الوقت الحالي، يُسمح فقط باستخدام Base64.

  • ضبط المحتوى

    فراغ

    لتعيين محتوى المورد.

    تبدو دالة setContent كما يلي: 

    (content: string, commit: boolean, callback?: function) => {...}

    • محتوى

      سلسلة

      تمثّل هذه السمة المحتوى الجديد في المرجع. لا تتوفّر حاليًا سوى الموارد ذات نوع النص.

    • الإتمام

      منطقي

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

    • رد الاتصال

      الدالة اختيارية

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

      (error?: object) => void

      • خطأ

        الكائن اختياري

        يتم ضبطها على "غير محدَّد" إذا تم ضبط محتوى المورد بنجاح. يصف الخطأ بطريقة أخرى.

أماكن إقامة

tabId

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

النوع

الرقم

الطُرق

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

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

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

      يمكنك تقييم التعبير في سياق النص البرمجي للمحتوى الخاص بالإضافة التي تتطابق مع المصدر المحدّد. إذا تم تحديد قيمة scriptExecutionContext، فستتجاوز القيمة "true". الإعداد على useContentScriptContext.

    • useContentScriptContext

      قيمة منطقية اختيارية

      قيِّم التعبير في سياق النص البرمجي للمحتوى الخاص بإضافة الاستدعاء، بشرط أن يكون النص البرمجي للمحتوى قد سبق إدخاله في الصفحة التي تم فحصها. وإذا لم يكن الأمر كذلك، لا يتم تقييم التعبير ويتم استدعاء دالة الاستدعاء مع ضبط معلَمة الاستثناء على كائن تم ضبط الحقل isError فيه على "صحيح" وضبط الحقل code على E_NOTFOUND.

  • رد الاتصال

    الدالة اختيارية

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

    (result: object, exceptionInfo: object) => void

    • نتيجة

      كائن

      هي نتيجة التقييم.

    • exceptionInfo

      كائن

      كائن يقدّم تفاصيل في حال حدوث استثناء أثناء تقييم التعبير.

      • رمز

        سلسلة

        يمكنك تحديد ما إذا كان الخطأ قد حدث من جانب "أدوات مطوري البرامج" قبل تقييم التعبير.

      • الوصف

        سلسلة

        يمكنك تحديد ما إذا كان الخطأ قد حدث من جانب "أدوات مطوري البرامج" قبل تقييم التعبير.

      • التفاصيل

        أي[]

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

      • isError

        منطقي

        يمكنك تحديد ما إذا كان الخطأ قد حدث من جانب "أدوات مطوري البرامج" قبل تقييم التعبير.

      • isException

        منطقي

        يمكنك ضبط هذا الإعداد إذا كانت التعليمة البرمجية التي تم تقييمها ينتج عنها استثناء لم تتم معالجته.

      • القيمة

        سلسلة

        يمكنك ضبط هذا الإعداد إذا كانت التعليمة البرمجية التي تم تقييمها ينتج عنها استثناء لم تتم معالجته.

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