Étendre les outils de développement

Présentation

Une extension DevTools ajoute des fonctionnalités aux outils pour les développeurs Chrome. Il peut ajouter de nouveaux panneaux et barres latérales d'interface utilisateur, interagir avec la page inspectée, obtenir des informations sur les requêtes réseau, etc. Affichez les extensions DevTools sélectionnées. Les extensions DevTools ont accès à un ensemble supplémentaire d'API d'extension spécifiques à DevTools:

Une extension DevTools est structurée comme n'importe quelle autre extension: elle peut comporter une page de fond, des scripts de contenu et d'autres éléments. De plus, chaque extension DevTools dispose d'une page DevTools, qui a accès aux API DevTools.

Schéma d'architecture montrant la page DevTools communiquant avec la fenêtre inspectée et la page en arrière-plan. La page en arrière-plan est représentée en train de communiquer avec les scripts de contenu et d'accéder aux API d'extension. La page des outils de développement a accès aux API des outils de développement, par exemple pour créer des panneaux.

Page des outils de développement

Une instance de la page DevTools de l'extension est créée chaque fois qu'une fenêtre DevTools s'ouvre. La page DevTools existe pendant toute la durée de vie de la fenêtre DevTools. La page DevTools a accès aux API DevTools et à un ensemble limité d'API d'extension. Plus précisément, la page des outils de développement peut:

  • Créez et interagissez avec des panneaux à l'aide des API devtools.panels.
  • Obtenez des informations sur la fenêtre inspectée et évaluez le code dans la fenêtre inspectée à l'aide des API devtools.inspectedWindow.
  • Obtenez des informations sur les requêtes réseau à l'aide des API devtools.network.

La page DevTools ne peut pas utiliser directement la plupart des API d'extension. Il a accès au même sous-ensemble des API extension et runtime qu'un script de contenu. Comme un script de contenu, une page DevTools peut communiquer avec la page en arrière-plan à l'aide du transfert de messages. Pour obtenir un exemple, consultez Injecter un script de contenu.

Créer une extension DevTools

Pour créer une page DevTools pour votre extension, ajoutez le champ devtools_page dans le fichier manifeste de l'extension:

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

Une instance de l'devtools_page spécifiée dans le fichier manifeste de votre extension est créée pour chaque fenêtre DevTools ouverte. La page peut ajouter d'autres pages d'extension en tant que panneaux et barres latérales à la fenêtre DevTools à l'aide de l'API devtools.panels.

Les modules de l'API chrome.devtools.* ne sont disponibles que pour les pages chargées dans la fenêtre DevTools. Les scripts de contenu et les autres pages d'extension ne disposent pas de ces API. Par conséquent, les API ne sont disponibles que pendant toute la durée de vie de la fenêtre DevTools.

Certaines API DevTools sont également encore en phase expérimentale. Reportez-vous à chrome.experimental.* API pour obtenir la liste des API expérimentales et des consignes d'utilisation.

Éléments d'interface utilisateur des outils de développement: panneaux et volets de la barre latérale

En plus des éléments d'interface utilisateur d'extension habituels, tels que les actions du navigateur, les menus contextuels et les pop-ups, une extension DevTools peut ajouter des éléments d'interface utilisateur à la fenêtre DevTools:

  • Un panneau est un onglet de premier niveau, comme les panneaux "Éléments", "Sources" et "Réseau".
  • Un volet de barre latérale présente une UI supplémentaire associée à un panneau. Les panneaux "Styles", "Styles calculés" et "Écouteurs d'événements" du panneau "Éléments" sont des exemples de panneaux de barre latérale. (Notez que l'apparence des panneaux de la barre latérale peut ne pas correspondre à l'image, en fonction de la version de Chrome que vous utilisez et de l'emplacement de la fenêtre des outils pour les développeurs.)

Fenêtre des outils de développement affichant le panneau "Éléments" et le volet "Styles" de la barre latérale.

Chaque panneau est un fichier HTML qui peut inclure d'autres ressources (JavaScript, CSS, images, etc.). Voici comment créer un panneau de base:

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

Le code JavaScript exécuté dans un panneau ou un volet de la barre latérale a accès aux mêmes API que la page DevTools.

Voici comment créer un volet de barre latérale de base pour le panneau "Éléments" :

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

Il existe plusieurs façons d'afficher du contenu dans un volet de la barre latérale:

  • Contenu HTML. Appelez setPage pour spécifier une page HTML à afficher dans le volet.
  • Données JSON. Transmettez un objet JSON à setObject.
  • Expression JavaScript. Transmettez une expression à setExpression. DevTools évalue l'expression dans le contexte de la page inspectée et affiche la valeur renvoyée.

Pour setObject et setExpression, le volet affiche la valeur telle qu'elle apparaît dans la console DevTools. Toutefois, setExpression vous permet d'afficher des éléments DOM et des objets JavaScript arbitraires, tandis que setObject n'est compatible qu'avec les objets JSON.

Communication entre les composants de l'extension

Les sections suivantes décrivent certains scénarios courants de communication entre les différents composants d'une extension DevTools.

Injecter un script de contenu

La page des outils de développement ne peut pas appeler directement tabs.executeScript. Pour injecter un script de contenu à partir de la page DevTools, vous devez récupérer l'ID de l'onglet de la fenêtre inspectée à l'aide de la propriété inspectedWindow.tabId et envoyer un message à la page en arrière-plan. Depuis la page en arrière-plan, appelez tabs.executeScript pour injecter le script.

Les extraits de code suivants montrent comment injecter un script de contenu à l'aide de 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"
});

Code de la page d'arrière-plan:

// 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);
    });
});

Évaluer JavaScript dans la fenêtre inspectée

Vous pouvez utiliser la méthode inspectedWindow.eval pour exécuter du code JavaScript dans le contexte de la page inspectée. Vous pouvez appeler la méthode eval à partir d'une page, d'un panneau ou d'un volet de la barre latérale des outils de développement.

Par défaut, l'expression est évaluée dans le contexte du frame principal de la page. Vous connaissez peut-être déjà les fonctionnalités de l'API de ligne de commande des outils de développement, comme l'inspection des éléments (inspect(elem)), l'arrêt sur les fonctions (debug(fn)), la copie dans le presse-papiers (copy()), etc. inspectedWindow.eval() utilise le même contexte et les mêmes options d'exécution de script que le code saisi dans la console DevTools, ce qui permet d'accéder à ces API dans l'évaluation. Par exemple, SOAK l'utilise pour inspecter un élément:

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

Vous pouvez également utiliser l'option useContentScriptContext: true pour inspectedWindow.eval() afin d'évaluer l'expression dans le même contexte que les scripts de contenu. L'appel de eval avec useContentScriptContext: true ne create pas de contexte de script de contenu. Vous devez donc charger un script de contexte avant d'appeler eval, soit en appelant executeScript, soit en spécifiant un script de contenu dans le fichier manifest.json.

Une fois le contexte du script de contexte créé, vous pouvez utiliser cette option pour injecter des scripts de contenu supplémentaires.

La méthode eval est puissante lorsqu'elle est utilisée dans le bon contexte et dangereuse lorsqu'elle est utilisée de manière inappropriée. Utilisez la méthode tabs.executeScript si vous n'avez pas besoin d'accéder au contexte JavaScript de la page inspectée. Pour obtenir des mises en garde détaillées et une comparaison des deux méthodes, consultez inspectedWindow.

Transmettre l'élément sélectionné à un script de contenu

Le script de contenu n'a pas d'accès direct à l'élément actuellement sélectionné. Toutefois, tout code que vous exécutez à l'aide de inspectedWindow.eval a accès à la console DevTools et aux API de ligne de commande. Par exemple, dans le code évalué, vous pouvez utiliser $0 pour accéder à l'élément sélectionné.

Pour transmettre l'élément sélectionné à un script de contenu:

  • Créez une méthode dans le script de contenu qui utilise l'élément sélectionné comme argument.
  • Appelez la méthode à partir de la page des outils de développement à l'aide de inspectedWindow.eval avec l'option useContentScriptContext: true.

Le code de votre script de contenu peut se présenter comme suit:

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

Appelez la méthode depuis la page des outils de développement comme suit:

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

L'option useContentScriptContext: true spécifie que l'expression doit être évaluée dans le même contexte que les scripts de contenu afin qu'elle puisse accéder à la méthode setSelectedElement.

Obtenir le window d'un panneau de référence

Pour postMessage à partir d'un panneau des outils pour les développeurs, vous avez besoin d'une référence à son objet window. Obtenez la fenêtre iframe d'un panneau à partir du gestionnaire d'événements panel.onShown:

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

Messagerie des scripts de contenu vers la page des outils de développement

La messagerie entre la page DevTools et les scripts de contenu est indirecte, via la page en arrière-plan.

Lorsque vous envoyez un message à un script de contenu, la page en arrière-plan peut utiliser la méthode tabs.sendMessage, qui dirige un message vers les scripts de contenu dans un onglet spécifique, comme illustré dans la section Injecter un script de contenu.

Lorsque vous envoyez un message à partir d'un script de contenu, il n'existe aucune méthode prête à l'emploi pour envoyer un message à l'instance de page DevTools appropriée associée à l'onglet actuel. Pour contourner ce problème, vous pouvez demander à la page DevTools d'établir une connexion durable avec la page en arrière-plan et à la page en arrière-plan de conserver une mise en correspondance des ID d'onglet avec les connexions afin qu'elle puisse acheminer chaque message vers la connexion appropriée.

// 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;
});

La page des outils de développement (ou le panneau ou le volet de la barre latérale) établit la connexion comme suit:

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

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

Messages des scripts injectés vers la page des outils de développement

Bien que la solution ci-dessus fonctionne pour les scripts de contenu, le code injecté directement dans la page (par exemple, en ajoutant une balise <script> ou via inspectedWindow.eval) nécessite une stratégie différente. Dans ce contexte, runtime.sendMessage ne transmettra pas de messages au script en arrière-plan comme prévu.

Pour contourner ce problème, vous pouvez combiner votre script injecté avec un script de contenu qui sert d'intermédiaire. Pour transmettre des messages au script de contenu, vous pouvez utiliser l'API window.postMessage. Voici un exemple, en supposant que vous utilisiez le script en arrière-plan de la section précédente:

// 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);
});

Votre message passe désormais du script injecté au script de contenu, au script en arrière-plan, puis à la page DevTools.

Vous pouvez également consulter deux autres techniques de transmission de messages ici.

Détecter quand DevTools s'ouvre et se ferme

Si votre extension doit déterminer si la fenêtre des outils de développement est ouverte, vous pouvez ajouter un écouteur onConnect à la page en arrière-plan et appeler connect à partir de la page des outils de développement. Étant donné que chaque onglet peut avoir sa propre fenêtre DevTools ouverte, vous pouvez recevoir plusieurs événements de connexion. Pour savoir si une fenêtre DevTools est ouverte, vous devez compter les événements de connexion et de déconnexion, comme indiqué ci-dessous:

// 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.");
          }
      });
    }
});

La page des outils de développement crée une connexion comme suit:

// devtools.js

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

Exemples d'extensions DevTools

Parcourez la source de ces exemples d'extensions DevTools:

En savoir plus

Pour en savoir plus sur les API standards que les extensions peuvent utiliser, consultez chrome.* API et API Web.

Envoyez-nous vos commentaires. Vos commentaires et suggestions nous aident à améliorer les API.

Exemples

Vous trouverez des exemples qui utilisent les API DevTools dans Samples (Exemples).