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

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

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

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

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

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

  • يمكنك إنشاء اللوحات والتفاعل معها باستخدام واجهات برمجة تطبيقات 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(). DevTools تقيّم التعبير في سياق الصفحة التي تم فحصها، ثم تعرض القيمة المعروضة.

بالنسبة إلى كل من 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() سياق تنفيذ النص البرمجي نفسه والخيارات نفسها كرمز برمجي يتم إدخالها في وحدة تحكّم أدوات مطوّري البرامج، وهي تتيح الوصول إلى أدوات وحدة التحكّم في أدوات مطوّري البرامج Google API عند استخدام 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() لديه إذن بالوصول إلى "أدوات مطوري البرامج" واجهات برمجة التطبيقات لـ Console ووحدة التحكم. على سبيل المثال، في الرمز المقيّم، يمكنك استخدام $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 DevTools: لاستخدام وحدة فرعية من العارض لإعادة استخدام واجهة مستخدم أدوات مطوّري البرامج والمكونات.
  • Ember Inspector: أداة أساسية للإضافة المشتركة مع محوّلات لكل من Chrome وFirefox.
  • Coquette-inspect: إضافة سليمة تستنِد إلى React مع إدخال وكيل لتصحيح الأخطاء إلى الصفحة المضيفة.
  • تحتوي نماذج الإضافات على إضافات أكثر جدارة فائدة لتثبيتها وتجربتها والتعلّم. منهم.

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

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

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

أمثلة

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