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

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

تشمل واجهات برمجة التطبيقات الخاصة بأدوات مطوّري البرامج ما يلي:

• devtools.inspectedWindow
• devtools.network
• devtools.panels
• devtools.recorder
• devtools.performance

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

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

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

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

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

لإنشاء صفحة "أدوات مطوّري البرامج" لإضافتك، أضِف الحقل devtools_page في بيان الإضافة:

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

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

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

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

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

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

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

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

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

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

chrome.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()، يعرض الجزء القيمة كما تظهر في وحدة تحكّم "أدوات مطوّري البرامج". مع ذلك، تتيح لك setExpression() عرض عناصر DOM وكائنات JavaScript عشوائية، بينما لا تتيح setObject() سوى كائنات JSON.

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

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

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

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

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

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

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

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

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

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

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

   chrome.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()، إرسال رسائل إلى صفحة "أدوات مطوّري البرامج" باستخدام 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;
  }

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

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

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

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

// background.js
var openCount = 0;
chrome.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 = chrome.runtime.connect({
    name: "devtools-page"
});

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

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

تأتي الأمثلة في هذه الصفحة من الصفحات التالية:

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

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

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

يُرجى إرسال ملاحظاتك إلينا. تساعدنا تعليقاتك واقتراحاتك في تحسين واجهات برمجة التطبيقات.

أمثلة

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