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

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

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

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

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

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

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

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

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

لإنشاء صفحة "أدوات مطوري البرامج" للإضافة، أضِف الحقل 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(). على سبيل المثال، تستخدمه الدالة SOAK لفحص عنصر ما:

chrome.devtools.inspectedWindow.eval(
  "inspect($$('head script[data-soak=main]')[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() من صفحة "أدوات مطوري البرامج". وبما أنّه يمكن فتح نافذة "أدوات مطوري البرامج" لكل علامة تبويب، قد تتلقّى أحداث ربط متعدّدة. لتتبُّع ما إذا كانت نافذة ضمن "أدوات مطوري البرامج" مفتوحة، يمكنك احتساب أحداث الربط وإلغاء الربط كما هو موضّح في المثال التالي:

// 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 Devtools - تستخدم العديد من المساعدين الذين تعمل في صفحة المضيف لطلب بحث حالة DOM/JS لإعادة الإرسال إلى اللوحة المخصّصة.
  • إضافة React DevTool: تستخدم وحدة فرعية من العارض لإعادة استخدام مكوّنات واجهة المستخدم في أدوات مطوّري البرامج.
  • Ember Inspector (أداة فحص بحد أقصى): يضم الإضافة الأساسية المشتركة مع محوّلات لكل من Chrome وFirefox.
  • Coquette-inspect: إضافة بسيطة مستندة إلى التفاعل مع إدخال وكيل لتصحيح الأخطاء في صفحة المضيف.
  • تحتوي نماذج الإضافات على المزيد من الإضافات المفيدة لتثبيتها وتجربتها والتعلّم منها.

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

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

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

أمثلة

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