توسيع أدوات مطوري البرامج

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

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

تتضمّن واجهات برمجة التطبيقات الخاصة بإضافات DevTools ما يلي:

صفحة "أدوات مطوّري البرامج"

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

  • يمكنك إنشاء اللوحات والتفاعل معها باستخدام واجهات برمجة التطبيقات devtools.panels، بما في ذلك إضافة صفحات إضافات أخرى كلوحات أو أشرطة جانبية إلى نافذة "أدوات مطوّري البرامج".
  • يمكنك الحصول على معلومات حول النافذة التي تم فحصها وتقييم الرمز البرمجي في النافذة التي تم فحصها باستخدام واجهات برمجة التطبيقات devtools.inspectedWindow.
  • يمكنك الحصول على معلومات حول طلبات الشبكة باستخدام واجهات برمجة التطبيقات devtools.network.
  • يمكنك توسيع لوحة "المسجّل" باستخدام واجهات برمجة التطبيقات devtools.recorder.
  • يمكنك الحصول على معلومات حول حالة التسجيل في لوحة الأداء باستخدام واجهات برمجة التطبيقات devtools.performance.

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

إنشاء إضافة لأدوات مطوّري البرامج

لإنشاء صفحة DevTools خاصة بإضافتك، أضِف الحقل devtools_page في ملف بيان الإضافة:

{
  "name": ...
  "version": "1.0",
  "devtools_page": "devtools.html",
  ...
}

يجب أن يشير الحقل devtools_page إلى صفحة HTML. بما أنّ صفحة DevTools يجب أن تكون محلية بالنسبة إلى الإضافة، ننصحك بتحديدها باستخدام عنوان URL نسبي.

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

مساحة اسم المتصفّح وإضافات "أدوات مطوّري البرامج"

في الإصدار 152 والإصدارات الأحدث من Chrome، يمكن للإضافات التي تتضمّن صفحة "أدوات مطوّري البرامج" استخدام مساحة الاسم browser.

في الإصدارات الأقدم من 152 من Chrome، تم إيقاف مساحة الاسم browser للإضافات التي تحدّد devtools_page. كانت عملية إيقاف المشاركة تنطبق على الإضافة بأكملها، وليس على صفحة DevTools فقط، بل على كل سياق نص برمجي يتم فيه تشغيل واجهات برمجة التطبيقات الخاصة بالإضافة.

كان السبب هو عدم التوافق مع webextension-polyfill. كانت واجهات برمجة التطبيقات browser.devtools.* قبل الإصدار 152 من Chrome تستخدم عمليات رد الاتصال فقط، أي أنّها لم تعرض Promises بشكل أصلي، لذا كانت إضافات "أدوات مطوّري البرامج" تعتمد عادةً على polyfill لتضمينها. يتخطّى رمز polyfill عملية التضمين كلّما تم تحديد browser، بافتراض أنّ المضيف قد أنجز العمل مسبقًا. إذا كان Chrome قد فعّل browser لهذه الإضافات، لن يتم تنفيذ polyfill، وستتوقف استدعاءات browser.devtools.* عن عرض Promises. أدى إيقاف browser إلى استمرار التفاف polyfill.

أدّى إيقاف الميزة نفسه أيضًا إلى إيقاف التغييرات الأخرى في واجهة برمجة التطبيقات للمراسلة في الإصدار 148 من Chrome لهذه الإضافات، بما في ذلك ردود Promise في runtime.onMessage. تم رفع القيود بعد أن أتاحت واجهات برمجة التطبيقات في "أدوات مطوّري البرامج" استخدام Promises بشكل أصلي.

عناصر واجهة مستخدم "أدوات مطوّري البرامج": اللوحات وألواح الشريط الجانبي

بالإضافة إلى عناصر واجهة المستخدم المعتادة للإضافات، مثل إجراءات المتصفّح وقوائم السياق والنوافذ المنبثقة، يمكن لإضافة DevTools إضافة عناصر واجهة مستخدم إلى نافذة DevTools:

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

كل لوحة هي ملف HTML مستقل يمكن أن يتضمّن موارد أخرى (JavaScript وCSS والصور وما إلى ذلك). لإنشاء لوحة أساسية، استخدِم الرمز التالي:

browser.devtools.panels.create("My Panel",
    "MyPanelIcon.png",
    "Panel.html",
    function(panel) {
      // code invoked on panel creation
    }
);

يمكن لرمز JavaScript الذي يتم تنفيذه في لوحة أو جزء من اللوحة الجانبية الوصول إلى واجهات برمجة التطبيقات نفسها التي يمكن لصفحة "أدوات مطوّري البرامج" الوصول إليها.

لإنشاء لوحة شريط جانبي أساسية، استخدِم الرمز التالي:

browser.devtools.panels.elements.createSidebarPane("My Sidebar",
    function(sidebar) {
        // sidebar initialization code here
        sidebar.setObject({ some_data: "Some data to show" });
});

هناك عدة طرق لعرض المحتوى في لوحة الشريط الجانبي:

  • محتوى HTML: استخدِم setPage() لتحديد صفحة HTML لعرضها في اللوحة.
  • بيانات JSON: مرِّر عنصر JSON إلى setObject().
  • تعبير JavaScript: مرِّر تعبيرًا إلى setExpression(). تقيِّم "أدوات مطوّري البرامج" التعبير في سياق الصفحة التي تم فحصها، ثم تعرض القيمة المعروضة.

بالنسبة إلى كل من setObject() وsetExpression()، تعرض اللوحة القيمة كما ستظهر في وحدة تحكّم DevTools. ومع ذلك، يتيح لك setExpression() عرض عناصر DOM وكائنات JavaScript عشوائية، بينما لا يتيح setObject() سوى كائنات JSON.

التواصل بين مكوّنات الإضافة

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

إضافة نص برمجي للمحتوى

لإدخال نص برمجي للمحتوى، استخدِم scripting.executeScript():

// DevTools page -- devtools.js
browser.scripting.executeScript({
  target: {
    tabId: browser.devtools.inspectedWindow.tabId
  },
  files: ["content_script.js"]
});

يمكنك استرداد معرّف علامة التبويب للنافذة التي تم فحصها باستخدام السمة inspectedWindow.tabId.

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

تقييم JavaScript في النافذة التي تم فحصها

يمكنك استخدام طريقة inspectedWindow.eval() لتنفيذ رمز JavaScript في سياق الصفحة التي يتم فحصها. يمكنك استدعاء طريقة eval() من صفحة أو لوحة أو جزء من الشريط الجانبي في "أدوات مطوّري البرامج".

يتمّ تقييم التعبير تلقائيًا في سياق الإطار الرئيسي للصفحة. تستخدم inspectedWindow.eval() سياق تنفيذ البرنامج النصي وخياراته نفسها المستخدَمة في الرمز البرمجي الذي تم إدخاله في وحدة تحكّم "أدوات مطوّري البرامج"، ما يتيح الوصول إلى ميزات واجهة برمجة التطبيقات الخاصة بأدوات Console Utilities في "أدوات مطوّري البرامج" عند استخدام eval(). على سبيل المثال، يمكنك استخدامها لفحص عنصر النص البرمجي الأول ضمن القسم <head> من مستند HTML:

browser.devtools.inspectedWindow.eval(
  "inspect($$('head script')[0])",
  function(result, isException) { }
);

يمكنك أيضًا ضبط useContentScriptContext على true عند استدعاء inspectedWindow.eval() لتقييم التعبير في السياق نفسه الذي تستخدمه البرامج النصية للمحتوى. لاستخدام هذا الخيار، استخدِم بيان نص برمجي للمحتوى الثابت قبل طلب eval()، إما عن طريق طلب executeScript() أو عن طريق تحديد نص برمجي للمحتوى في الملف manifest.json. بعد تحميل سياق النص البرمجي للمحتوى، يمكنك أيضًا استخدام هذا الخيار لإدخال نصوص برمجية إضافية للمحتوى.

تمرير العنصر المحدّد إلى نص برمجي خاص بالمحتوى

لا يمكن لبرنامج نص المحتوى الوصول مباشرةً إلى العنصر المحدّد حاليًا. ومع ذلك، يمكن لأي رمز تنفّذه باستخدام inspectedWindow.eval() الوصول إلى وحدة تحكّم أدوات مطوّري البرامج وواجهات برمجة التطبيقات لأدوات وحدة التحكّم. على سبيل المثال، في الرمز البرمجي الذي تم تقييمه، يمكنك استخدام $0 للوصول إلى العنصر المحدّد.

لتمرير العنصر المحدّد إلى نص برمجي خاص بالمحتوى، اتّبِع الخطوات التالية:

  1. أنشئ طريقة في نص المحتوى تأخذ العنصر المحدّد كمعلَمة.

    function setSelectedElement(el) {
    // do something with the selected element
}

  2. استدعِ الطريقة من صفحة "أدوات مطوّري البرامج" باستخدام inspectedWindow.eval() مع الخيار useContentScriptContext: true.

    browser.devtools.inspectedWindow.eval("setSelectedElement($0)",
    { useContentScriptContext: true });

يحدّد الخيار useContentScriptContext: true أنّه يجب تقييم التعبير في السياق نفسه الذي يتم فيه تقييم نصوص المحتوى البرمجية، وبالتالي يمكنه الوصول إلى الطريقة setSelectedElement.

الحصول على window في لوحة المستند المرجعي

لطلب postMessage() من لوحة أدوات مطوّلين، ستحتاج إلى مرجع إلى العنصر window. الحصول على نافذة iframe للوحة من معالج الأحداث panel.onShown:

extensionPanel.onShown.addListener(function (extPanelWindow) {
    extPanelWindow instanceof Window; // true
    extPanelWindow.postMessage( // …
});

إرسال رسائل من البرامج النصية التي تم إدخالها إلى صفحة "أدوات مطوّري البرامج"

لا يمكن للرمز الذي يتم إدراجه مباشرةً في الصفحة بدون نص برمجي للمحتوى، بما في ذلك عن طريق إضافة علامة <script> أو استدعاء inspectedWindow.eval()، إرسال رسائل إلى صفحة DevTools باستخدام runtime.sendMessage(). بدلاً من ذلك، ننصحك بدمج النص البرمجي الذي تم إدراجه مع نص برمجي للمحتوى يمكن أن يعمل كوسيط، واستخدام طريقة window.postMessage(). يستخدم المثال التالي النص البرمجي للخلفية من القسم السابق:

// injected-script.js

window.postMessage({
  greeting: 'hello there!',
  source: 'my-devtools-extension'
}, '*');

// content-script.js

window.addEventListener('message', function(event) {
  // Only accept messages from the same frame
  if (event.source !== window) {
    return;
  }

  var message = event.data;

  // Only accept messages that we know are ours. Note that this is not foolproof
  // and the page can easily spoof messages if it wants to.
  if (typeof message !== 'object' || message === null ||
      message.source !== 'my-devtools-extension') {
    return;
  }

  browser.runtime.sendMessage(message);
});

يمكن العثور على تقنيات أخرى بديلة لتمرير الرسائل على GitHub.

رصد وقت فتح "أدوات مطوّري البرامج" وإغلاقها

لتتبُّع ما إذا كانت نافذة "أدوات مطوّري البرامج" مفتوحة، أضِف أداة معالجة onConnect إلى عامل الخدمة واستدعِ connect() من صفحة "أدوات مطوّري البرامج". بما أنّ كل علامة تبويب يمكن أن يكون لها نافذة "أدوات مطوّري البرامج" مفتوحة، قد تتلقّى أحداث ربط متعدّدة. لتتبُّع ما إذا كانت أي نافذة من "أدوات مطوّلي البرامج" مفتوحة، احسب أحداث الربط وإلغاء الربط كما هو موضّح في المثال التالي:

// background.js
var openCount = 0;
browser.runtime.onConnect.addListener(function (port) {
    if (port.name == "devtools-page") {
      if (openCount == 0) {
        alert("DevTools window opening.");
      }
      openCount++;

      port.onDisconnect.addListener(function(port) {
          openCount--;
          if (openCount == 0) {
            alert("Last DevTools window closing.");
          }
      });
    }
});

تنشئ صفحة "أدوات مطوّري البرامج" اتصالاً على النحو التالي:

// devtools.js

// Create a connection to the service worker
const serviceWorkerConnection = browser.runtime.connect({
    name: "devtools-page"
});

// Send a periodic heartbeat to keep the port open.
setInterval(() => {
  port.postMessage("heartbeat");
}, 15000);

أمثلة على إضافات "أدوات مطوّري البرامج"

تستند الأمثلة الواردة في هذه الصفحة إلى الصفحات التالية:

  • إضافة Polymer Devtools: تستخدم العديد من الأدوات المساعدة التي تعمل في صفحة المضيف للاستعلام عن حالة DOM/JS وإرسالها إلى اللوحة المخصّصة.
  • إضافة React DevTools: تستخدم وحدة فرعية من أداة العرض لإعادة استخدام مكوّنات واجهة مستخدم "أدوات مطوّري البرامج".
  • Ember Inspector: مكوّن إضافي أساسي مشترك مع محوّلات لكل من Chrome وFirefox.
  • Coquette-inspect: إضافة بسيطة مستندة إلى React تتضمّن أداة لتصحيح الأخطاء يتم إدراجها في صفحة المضيف.
  • تتضمّن الإضافات النموذجية المزيد من الإضافات المفيدة التي يمكنك تثبيتها وتجربتها والاستفادة منها.

مزيد من المعلومات

للحصول على معلومات حول واجهات برمجة التطبيقات العادية التي يمكن أن تستخدمها الإضافات، يُرجى الاطّلاع على browser.* واجهات برمجة التطبيقات وواجهات برمجة التطبيقات على الويب.

مشاركة ملاحظاتك وآرائك تساعدنا تعليقاتك واقتراحاتك في تحسين واجهات برمجة التطبيقات.

أمثلة

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