chrome.devtools.inspectedWindow

الوصف

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

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

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

يمكن استخدام الطريقة 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 وسيطة ثانية اختيارية يمكنك استخدامها لتحديد السياق الذي يتم فيه تقييم الرمز. يمكن أن يحتوي كائن الخيارات هذا على مفتاح واحد أو أكثر من المفاتيح التالية:

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-samples.

الأنواع

Resource

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

الخصائص

  • url

    سلسلة

    تمثّل هذه السمة عنوان URL الخاص بالمرجع.

  • getContent

    باطل

    تعرض هذه السمة محتوى المرجع.

    تبدو الدالة getContent على النحو التالي: 

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

    • callback

      دالة

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

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

      • المحتوى

        سلسلة

        محتوى المورد (قد يكون مشفّرًا)

      • الترميز

        سلسلة

        يكون هذا الحقل فارغًا إذا لم يكن المحتوى مشفّرًا، أو يتضمّن اسم التشفير في حال كان المحتوى مشفّرًا. لا تتوفّر حاليًا سوى base64.

  • setContent

    باطل

    تضبط هذه السمة محتوى المورد.

    تبدو الدالة setContent على النحو التالي: 

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

    • المحتوى

      سلسلة

      المحتوى الجديد للمرجع لا تتوفّر حاليًا إلا المراجع التي تتضمّن النوع النصي.

    • الإتمام

      قيمة منطقية

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

    • callback

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

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

      (error?: object) => void

      • خطأ

        عنصر اختياري

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

الخصائص

tabId

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

النوع

الرقم

الطُرق

eval()

chrome.devtools.inspectedWindow.eval(
  expression: string,
  options?: object,
  callback?: function,
): void

تقييم تعبير JavaScript في سياق الإطار الرئيسي للصفحة التي يتم فحصها يجب أن يتم تقييم التعبير إلى عنصر متوافق مع JSON، وإلا سيتم طرح استثناء. يمكن أن تعرض الدالة eval إما خطأ من جهة "أدوات مطوّري البرامج" أو استثناء JavaScript يحدث أثناء التقييم. في كلتا الحالتين، تكون قيمة المَعلمة result لدالة رد الاتصال هي undefined. في حال حدوث خطأ من جهة "أدوات مطوّري البرامج"، تكون المَعلمة isException غير فارغة ويتم ضبط isError على "صحيح" وضبط code على رمز خطأ. في حال حدوث خطأ في JavaScript، يتم ضبط isException على "صحيح" وضبط value على قيمة السلسلة للعنصر الذي تم طرحه.

المعلمات

  • تعبير

    سلسلة

    تعبير مطلوب تقييمه.

  • الخيارات

    عنصر اختياري

    يمكن أن تحتوي المَعلمة options على خيار واحد أو أكثر.

    • frameURL

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

      في حال تحديدها، يتم تقييم التعبير على إطار iframe الذي يتطابق عنوان URL الخاص به مع العنوان المحدّد. يتم تلقائيًا تقييم التعبير في الإطار العلوي للصفحة التي تم فحصها.

    • scriptExecutionContext

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

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

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

    • useContentScriptContext

      boolean اختياري

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

  • callback

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

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

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

    • نتيجة

      عنصر

      تمثّل هذه السمة نتيجة التقييم.

    • exceptionInfo

      عنصر

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

      • رمز

        سلسلة

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

      • الوصف

        سلسلة

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

      • التفاصيل

        any[]

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

      • isError

        قيمة منطقية

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

      • isException

        قيمة منطقية

        تحديد ما إذا كان الرمز الذي تم تقييمه ينتج عنه استثناء لم تتم معالجته

      • القيمة

        سلسلة

        تحديد ما إذا كان الرمز الذي تم تقييمه ينتج عنه استثناء لم تتم معالجته

getResources()

chrome.devtools.inspectedWindow.getResources(
  callback: function,
): void

تعرض هذه الطريقة قائمة الموارد من الصفحة التي يتم فحصها.

المعلمات

  • callback

    دالة

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

    (resources: Resource[]) => void

    • المراجع

      Resource[]

      الموارد داخل الصفحة

reload()

chrome.devtools.inspectedWindow.reload(
  reloadOptions?: object,
): void

تعيد هذه الأداة تحميل الصفحة التي تم فحصها.

المعلمات

  • reloadOptions

    عنصر اختياري

    • ignoreCache

      boolean اختياري

      عندما تكون القيمة صحيحة، سيتجاوز برنامج التحميل ذاكرة التخزين المؤقت لجميع موارد الصفحة التي تم فحصها والتي تم تحميلها قبل تنشيط الحدث load. ويشبه التأثير الضغط على Ctrl+Shift+R في النافذة التي تم فحصها أو داخل نافذة "أدوات المطوّرين".

    • injectedScript

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

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

    • userAgent

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

      في حال تحديد السلسلة، ستتجاوز قيمة عنوان HTTP User-Agent الذي يتم إرساله أثناء تحميل موارد الصفحة التي يتم فحصها. ستلغي السلسلة أيضًا قيمة السمة navigator.userAgent التي يتم عرضها لأي نصوص برمجية يتم تشغيلها داخل الصفحة التي تم فحصها.

الفعاليات

onResourceAdded

chrome.devtools.inspectedWindow.onResourceAdded.addListener(
  callback: function,
)

يتم تنشيط هذا الحدث عند إضافة مرجع جديد إلى الصفحة التي يتم فحصها.

المعلمات

  • callback

    دالة

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

    (resource: Resource) => void

onResourceContentCommitted

chrome.devtools.inspectedWindow.onResourceContentCommitted.addListener(
  callback: function,
)

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

المعلمات

  • callback

    دالة

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

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