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

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

الأنواع

Resource

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

الخصائص

  • url

    سلسلة

    عنوان URL للمرجع

  • getContent

    void

    Promise

    للحصول على محتوى المرجع

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

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

    • callback

      function اختياري

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

      (response: object) => void

      • رد

        عنصر

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

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

        • المحتوى

          سلسلة

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

        • الترميز

          سلسلة

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

    • returns

      وعد<كائن>

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

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

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

  • setContent

    void

    Promise

    لضبط محتوى المرجع

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

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

    • المحتوى

      سلسلة

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

    • الإتمام

      قيمة منطقية

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

    • callback

      function اختياري

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

      (error?: object) => void

      • خطأ

        object اختياري

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

    • returns

      وعد<كائن>

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

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

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

الخصائص

tabId

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

النوع

الرقم

الطُرق

eval()

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

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

المعلمات

  • تعبير

    سلسلة

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

  • الخيارات

    object اختياري

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

    • frameURL

      string اختياري

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

    • scriptExecutionContext

      string اختياري

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

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

    • useContentScriptContext

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

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

  • callback

    function اختياري

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

    (response: object) => void

    • رد

      عنصر

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

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

      • exceptionInfo

        عنصر

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

        • رمز

          سلسلة

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

        • الوصف

          سلسلة

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

        • التفاصيل

          any[]

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

        • isError

          قيمة منطقية

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

        • isException

          قيمة منطقية

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

        • القيمة

          سلسلة

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

      • نتيجة

        عنصر

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

المرتجعات

  • وعد<كائن>

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

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

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

getResources()

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

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

المعلمات

  • callback

    function اختياري

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

    (resources: Resource[]) => void

    • المراجع

      Resource[]

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

المرتجعات

  • Promise<Resource[]>

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

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

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

reload()

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

لإعادة تحميل الصفحة التي يتم فحصها

المعلمات

  • reloadOptions

    object اختياري

    • ignoreCache

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

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

    • injectedScript

      string اختياري

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

    • userAgent

      string اختياري

      في حال تحديد السلسلة، سيتم تجاهل قيمة عنوان 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