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

نظرة عامة

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

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

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

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

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

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

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

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

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

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

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

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

هناك أيضًا بعض واجهات برمجة تطبيقات DevTools التي لا تزال تجريبية. راجِع chrome.experimental.* واجهات برمجة التطبيقات للحصول على قائمة واجهات برمجة التطبيقات التجريبية وإرشادات حول كيفية استخدامها

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

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

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

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

توضِّح الأقسام التالية بعض السيناريوهات المعتادة للتواصل بين المكونات المختلفة لإحدى إضافات DevTools.

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

لا يمكن لصفحة "أدوات مطوري البرامج" طلب tabs.executeScript مباشرةً. لحقن نص برمجي للمحتوى من صفحة أدوات المطوّرين، يجب استرداد معرّف علامة تبويب النافذة التي يتم فحصها باستخدام السمة inspectedWindow.tabId وإرسال رسالة إلى صفحة الخلفية. من صفحة الخلفية، اتصل بـ tabs.executeScript لإدراج النص البرمجي.

توضِّح مقتطفات الرمز التالية كيفية إدخال نص برمجي للمحتوى باستخدام executeScript.

// DevTools page -- devtools.js
// Create a connection to the background page
var backgroundPageConnection = chrome.runtime.connect({
    name: "devtools-page"
});

backgroundPageConnection.onMessage.addListener(function (message) {
    // Handle responses from the background page, if any
});

// Relay the tab ID to the background page
chrome.runtime.sendMessage({
    tabId: chrome.devtools.inspectedWindow.tabId,
    scriptToInject: "content_script.js"
});

رمز صفحة الخلفية:

// Background page -- background.js
chrome.runtime.onConnect.addListener(function(devToolsConnection) {
    // assign the listener function to a variable so we can remove it later
    var devToolsListener = function(message, sender, sendResponse) {
        // Inject a content script into the identified tab
        chrome.tabs.executeScript(message.tabId,
            { file: message.scriptToInject });
    }
    // add the listener
    devToolsConnection.onMessage.addListener(devToolsListener);

    devToolsConnection.onDisconnect.addListener(function() {
         devToolsConnection.onMessage.removeListener(devToolsListener);
    });
});

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

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

يتم تقييم التعبير تلقائيًا في سياق الإطار الرئيسي للصفحة. الآن، يمكنك الإلمام بميزات commandline API الخاصة بأدوات مطوري البرامج، مثل فحص العناصر (inspect(elem))، توقف الوظائف (debug(fn))، والنسخ إلى الحافظة (copy()) والمزيد. يستخدم inspectedWindow.eval() سياق تنفيذ النصوص البرمجية وخياراتها نفسها المستخدَمة في الرمز المكتوب في وحدة تحكّم أدوات المطوّرين، ما يسمح بالوصول إلى واجهات برمجة التطبيقات هذه ضمن دالة eval. على سبيل المثال، يستخدم SOAK هذه الطريقة لفحص عنصر:

chrome.devtools.inspectedWindow.eval(
  "inspect($$('head script[data-soak=main]')[0])",
  function(result, isException) { }
);

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

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

إنّ طريقة eval فعّالة عند استخدامها في السياق الصحيح، وخطيرة عند استخدامها بشكل غير ملائم. استخدِم الطريقة tabs.executeScript إذا لم تكن بحاجة إلى الوصول إلى سياق JavaScript للصفحة التي تم فحصها للحصول على تحذيرات تفصيلية ومقارنة بين الطريقتَين، يُرجى الاطّلاع على inspectedWindow.

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

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

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

  • يمكنك إنشاء طريقة في النص البرمجي للمحتوى تستخدم العنصر المحدد كوسيطة.
  • يمكنك استدعاء الطريقة من صفحة "أدوات مطوري البرامج" باستخدام inspectedWindow.eval مع useContentScriptContext: true الخيار.

قد تبدو التعليمة البرمجية في النص البرمجي للمحتوى كما يلي:

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

استدع الطريقة من صفحة "أدوات مطوري البرامج" على النحو التالي:

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

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

الحصول على window للوحة مرجعية

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

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

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

تكون المراسلة بين صفحة "أدوات مطوّري البرامج" والنصوص البرمجية للمحتوى غير مباشرة، وذلك من خلال صفحة الخلفية.

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

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

// background.js
var connections = {};

chrome.runtime.onConnect.addListener(function (port) {

    var extensionListener = function (message, sender, sendResponse) {

        // The original connection event doesn't include the tab ID of the
        // DevTools page, so we need to send it explicitly.
        if (message.name == "init") {
          connections[message.tabId] = port;
          return;
        }

    // other message handling
    }

    // Listen to messages sent from the DevTools page
    port.onMessage.addListener(extensionListener);

    port.onDisconnect.addListener(function(port) {
        port.onMessage.removeListener(extensionListener);

        var tabs = Object.keys(connections);
        for (var i=0, len=tabs.length; i < len; i++) {
          if (connections[tabs[i]] == port) {
            delete connections[tabs[i]]
            break;
          }
        }
    });
});

// Receive message from content script and relay to the devTools page for the
// current tab
chrome.runtime.onMessage.addListener(function(request, sender, sendResponse) {
    // Messages from content scripts should have sender.tab set
    if (sender.tab) {
      var tabId = sender.tab.id;
      if (tabId in connections) {
        connections[tabId].postMessage(request);
      } else {
        console.log("Tab not found in connection list.");
      }
    } else {
      console.log("sender.tab not defined.");
    }
    return true;
});

تُنشئ صفحة أدوات مطوّري البرامج (أو اللوحة أو مساحة الشريط الجانبي) الاتصال على النحو التالي:

// Create a connection to the background page
var backgroundPageConnection = chrome.runtime.connect({
    name: "panel"
});

backgroundPageConnection.postMessage({
    name: 'init',
    tabId: chrome.devtools.inspectedWindow.tabId
});

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

على الرغم من أنّ الحلّ أعلاه يناسب نصوص المحتوى البرمجية، إلا أنّ الرمز الذي يتم إدخاله مباشرةً في الصفحة (مثلاً من خلال إلحاق علامة <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
  if (typeof message !== 'object' || message === null ||
      !message.source === 'my-devtools-extension') {
    return;
  }

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

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

يمكنك أيضًا الاطّلاع على طريقتَين بديلتَين لنقل الرسائل هنا.

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

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

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

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

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

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

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

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

أمثلة

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