chrome.devtools.inspectedWindow

refresh date: 2026-09-25 robots: noindex

الوصف

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

البيان

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

"devtools_page"

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

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

نظرة عامة

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

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

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 على النحو التالي: 

      (response: object) => void

      • رد

        عنصر

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

        كائن يحتوي على محتوى المرجع والترميز الخاص به

        • المحتوى

          سلسلة

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

        • الترميز

          سلسلة

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

    • returns

      Promise<object>

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

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

      لا تتوفّر الوعود إلا في الإصدار Manifest V3 والإصدارات الأحدث، بينما تحتاج المنصات الأخرى إلى استخدام عمليات معاودة الاتصال.

  • setContent

    باطل

    وعد

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

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

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

    • المحتوى

      سلسلة

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

    • الإتمام

      قيمة منطقية

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

    • callback

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

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

      (error?: object) => void

      • خطأ

        كائن اختياري

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

    • returns

      Promise<object>

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

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

      لا تتوفّر الوعود إلا في الإصدار Manifest V3 والإصدارات الأحدث، بينما تحتاج المنصات الأخرى إلى استخدام عمليات معاودة الاتصال.

الخصائص

tabId

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

النوع

الرقم

الطُرق

eval()

وعد 
chrome.devtools.inspectedWindow.eval(
  expression: string,
  options?: object,
  callback?: function,
): Promise<object>

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

المعلمات

  • تعبير

    سلسلة

    تعبير يجب تقييمه

  • الخيارات

    كائن اختياري

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

    • frameURL

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

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

    • scriptExecutionContext

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

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

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

    • useContentScriptContext

      boolean اختياري

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

  • callback

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

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

    (response: object) => void

    • رد

      عنصر

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

      نتيجة التقييم ومعلومات الاستثناء

      • exceptionInfo

        عنصر

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

        • رمز

          سلسلة

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

        • الوصف

          سلسلة

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

        • التفاصيل

          any[]

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

        • isError

          قيمة منطقية

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

        • isException

          قيمة منطقية

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

        • القيمة

          سلسلة

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

      • نتيجة

        عنصر

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

المرتجعات

  • Promise<object>

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

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

    لا تتوفّر الوعود إلا في الإصدار Manifest V3 والإصدارات الأحدث، بينما تحتاج المنصات الأخرى إلى استخدام عمليات معاودة الاتصال.

getResources()

وعد 
chrome.devtools.inspectedWindow.getResources(
  callback?: function,
): Promise<Resource[]>

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

المعلمات

  • callback

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

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

    (resources: Resource[]) => void

    • المراجع

      Resource[]

      المراجع داخل الصفحة

المرتجعات

  • Promise<Resource[]>

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

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

    لا تتوفّر الوعود إلا في الإصدار Manifest V3 والإصدارات الأحدث، بينما تحتاج المنصات الأخرى إلى استخدام عمليات معاودة الاتصال.

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