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 من مستودع chrome-extension-samples.

الأنواع

Resource

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

الخصائص

  • url

    سلسلة

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

  • getContent

    إلغاء

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

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

    () => {...}

    • returns

      Promise<object>

      في انتظار المراجعة

      دالة تتلقّى محتوى المورد عند اكتمال الطلب

  • setContent

    باطل

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

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

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

    • المحتوى

      سلسلة

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

    • الإتمام

      قيمة منطقية

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

    • returns

      Promise<object>

      في انتظار المراجعة

      دالة يتم استدعاؤها عند اكتمال الطلب.

الخصائص

tabId

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

النوع

الرقم

الطُرق

eval()

chrome.devtools.inspectedWindow.eval(
  expression: string,
  options?: object,
): Promise<object>

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

المعلمات

  • تعبير

    سلسلة

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

  • الخيارات

    كائن اختياري

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

    • frameURL

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

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

    • scriptExecutionContext

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

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

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

    • useContentScriptContext

      boolean اختياري

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

المرتجعات

  • Promise<object>

    في انتظار المراجعة

    دالة يتم استدعاؤها عند اكتمال التقييم.

getResources()

chrome.devtools.inspectedWindow.getResources(): Promise<Resource[]>

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

المرتجعات

  • Promise<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