chrome.devtools.inspectedWindow

refresh date: 2026-09-25 robots: noindex

Description

Utilisez l'API chrome.devtools.inspectedWindow pour interagir avec la fenêtre inspectée : obtenez l'ID de l'onglet de la page inspectée, évaluez le code dans le contexte de la fenêtre inspectée, actualisez la page ou obtenez la liste des ressources de la page.

Fichier manifeste

Les clés suivantes doivent être déclarées dans le fichier manifeste pour utiliser cette API.

"devtools_page"

Utilisez chrome.devtools.inspectedWindow pour interagir avec la fenêtre inspectée : obtenez l'ID d'onglet de la page inspectée, évaluez le code dans le contexte de la fenêtre inspectée, actualisez la page ou obtenez la liste des ressources de la page.

Consultez Résumé des API DevTools pour une présentation générale de l'utilisation des API des outils pour les développeurs.

Présentation

La propriété tabId fournit l'identifiant d'onglet que vous pouvez utiliser avec les appels d'API chrome.tabs.*. Toutefois, notez que l'API chrome.tabs.* n'est pas exposée aux pages d'extension des outils pour les développeurs pour des raisons de sécurité. Vous devez transmettre l'ID de l'onglet à la page d'arrière-plan et appeler les fonctions de l'API chrome.tabs.* à partir de là.

La méthode reload peut être utilisée pour actualiser la page inspectée. De plus, l'appelant peut spécifier un remplacement de la chaîne user-agent, un script qui sera injecté au début du chargement de page ou une option permettant de forcer l'actualisation des ressources mises en cache.

Utilisez l'appel getResources et l'événement onResourceContent pour obtenir la liste des ressources (documents, feuilles de style, scripts, images, etc.) de la page inspectée. Les méthodes getContent et setContent de la classe Resource, ainsi que l'événement onResourceContentCommitted, peuvent être utilisés pour permettre la modification du contenu de la ressource, par exemple par un éditeur externe.

Exécuter du code dans la fenêtre inspectée

La méthode eval permet aux extensions d'exécuter du code JavaScript dans le contexte de la page inspectée. Cette méthode est puissante lorsqu'elle est utilisée dans le bon contexte, mais dangereuse lorsqu'elle est utilisée de manière inappropriée. Utilisez la méthode tabs.executeScript, sauf si vous avez besoin de la fonctionnalité spécifique fournie par la méthode eval.

Voici les principales différences entre les méthodes eval et tabs.executeScript :

  • La méthode eval n'utilise pas de monde isolé pour le code évalué. L'état JavaScript de la fenêtre inspectée est donc accessible au code. Utilisez cette méthode lorsque l'accès à l'état JavaScript de la page inspectée est requis.
  • Le contexte d'exécution du code évalué inclut l'API de la console des outils pour les développeurs. Par exemple, le code peut utiliser inspect et $0.
  • Le code évalué peut renvoyer une valeur qui est transmise au rappel de l'extension. La valeur renvoyée doit être un objet JSON valide (elle ne peut contenir que des types JavaScript primitifs et des références acycliques à d'autres objets JSON). Soyez particulièrement prudent lorsque vous traitez les données reçues de la page inspectée. Le contexte d'exécution est essentiellement contrôlé par la page inspectée. Une page malveillante peut affecter les données renvoyées à l'extension.

Notez qu'une page peut inclure plusieurs contextes d'exécution JavaScript différents. Chaque frame possède son propre contexte, ainsi qu'un contexte supplémentaire pour chaque extension dont les scripts de contenu s'exécutent dans ce frame.

Par défaut, la méthode eval s'exécute dans le contexte du frame principal de la page inspectée.

La méthode eval accepte un deuxième argument facultatif que vous pouvez utiliser pour spécifier le contexte dans lequel le code est évalué. Cet objet options peut contenir une ou plusieurs des clés suivantes :

frameURL
Permet de spécifier un frame autre que le frame principal de la page inspectée.
contextSecurityOrigin
Permet de sélectionner un contexte dans le cadre spécifié en fonction de son origine Web.
useContentScriptContext
Si la valeur est "true", exécutez le script dans le même contexte que les scripts de contenu de l'extension. (Cela équivaut à spécifier l'origine Web de l'extension comme origine de sécurité du contexte.) Cela peut être utilisé pour échanger des données avec le script de contenu.

Exemples

Le code suivant vérifie la version de jQuery utilisée par la page inspectée :

chrome.devtools.inspectedWindow.eval(
  "jQuery.fn.jquery",
  function(result, isException) {
    if (isException) {
      console.log("the page is not using jQuery");
    } else {
      console.log("The page is using jQuery v" + result);
    }
  }
);

Pour essayer cette API, installez les exemples d'API devtools à partir du dépôt chrome-extension-samples.

Types

Resource

Ressource de la page inspectée, telle qu'un document, un script ou une image.

Propriétés

  • url

    chaîne

    URL de la ressource.

  • getContent

    vide

    Promise

    Récupère le contenu de la ressource.

    La fonction getContent se présente comme suit : 

    (callback?: function) => {...}

    • callback

      function facultatif

      Le paramètre callback se présente comme suit : 

      (response: object) => void

      • réponse

        objet

        Chrome 151 ou version ultérieure

        Objet contenant le contenu de la ressource et son encodage.

        • contenu

          chaîne

          Contenu de la ressource (potentiellement encodé).

        • encoding

          chaîne

          Vide si le contenu n'est pas encodé, nom de l'encodage sinon. Actuellement, seul le format base64 est accepté.

    • Renvoie

      Promise<object>

      Chrome 151 ou version ultérieure

      Fonction qui reçoit le contenu de la ressource une fois la requête terminée.

      Les promesses ne sont compatibles qu'avec Manifest V3 et les versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

  • setContent

    vide

    Promise

    Définit le contenu de la ressource.

    La fonction setContent se présente comme suit : 

    (content: string, commit: boolean, callback?: function) => {...}

    • contenu

      chaîne

      Nouveau contenu de la ressource. Seules les ressources de type texte sont actuellement acceptées.

    • commit

      booléen

      "True" si l'utilisateur a terminé de modifier la ressource et que le nouveau contenu de la ressource doit être conservé ; "False" s'il s'agit d'une modification mineure envoyée pendant que l'utilisateur modifie la ressource.

    • callback

      function facultatif

      Le paramètre callback se présente comme suit : 

      (error?: object) => void

      • erreur

        objet facultatif

        Défini sur "undefined" si le contenu de la ressource a bien été défini. Sinon, décrit l'erreur.

    • Renvoie

      Promise<object>

      Chrome 151 ou version ultérieure

      Fonction appelée à la fin de la requête.

      Les promesses ne sont compatibles qu'avec Manifest V3 et les versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

Propriétés

tabId

ID de l'onglet inspecté. Cet ID peut être utilisé avec chrome.tabs.* API REST.

Type

nombre

Méthodes

eval()

Promise 
chrome.devtools.inspectedWindow.eval(
  expression: string,
  options?: object,
  callback?: function,
): Promise<object>

Évalue une expression JavaScript dans le contexte du frame principal de la page inspectée. L'expression doit correspondre à un objet conforme au format JSON, sinon une exception est générée. La fonction eval peut signaler une erreur côté DevTools ou une exception JavaScript qui se produit lors de l'évaluation. Dans les deux cas, le paramètre result du rappel est undefined. En cas d'erreur côté DevTools, le paramètre isException n'est pas nul, isError est défini sur "true" et code est défini sur un code d'erreur. En cas d'erreur JavaScript, isException est défini sur "true" et value est défini sur la valeur de chaîne de l'objet généré.

Paramètres

  • expression

    chaîne

    Expression à évaluer.

  • options

    objet facultatif

    Le paramètre "options" peut contenir une ou plusieurs options.

    • frameURL

      chaîne facultatif

      Si elle est spécifiée, l'expression est évaluée sur l'iFrame dont l'URL correspond à celle spécifiée. Par défaut, l'expression est évaluée dans le frame supérieur de la page inspectée.

    • scriptExecutionContext

      chaîne facultatif

      Chrome 107 ou version ultérieure

      Évalue l'expression dans le contexte d'un script de contenu d'une extension correspondant à l'origine spécifiée. S'il est fourni, scriptExecutionContext remplace le paramètre "true" sur useContentScriptContext.

    • useContentScriptContext

      boolean facultatif

      Évalue l'expression dans le contexte du script de contenu de l'extension appelante, à condition que le script de contenu soit déjà injecté dans la page inspectée. Si ce n'est pas le cas, l'expression n'est pas évaluée et le rappel est appelé avec le paramètre d'exception défini sur un objet dont le champ isError est défini sur "true" et le champ code sur E_NOTFOUND.

  • callback

    function facultatif

    Le paramètre callback se présente comme suit : 

    (response: object) => void

    • réponse

      objet

      Chrome 151 ou version ultérieure

      Résultat de l'évaluation et informations sur l'exception.

      • exceptionInfo

        objet

        Objet fournissant des détails si une exception s'est produite lors de l'évaluation de l'expression.

        • code

          chaîne

          Défini si l'erreur s'est produite côté DevTools avant l'évaluation de l'expression.

        • description

          chaîne

          Défini si l'erreur s'est produite côté DevTools avant l'évaluation de l'expression.

        • détails

          any[]

          Défini si l'erreur s'est produite du côté des outils de développement avant l'évaluation de l'expression. Contient le tableau des valeurs pouvant être substituées dans la chaîne de description pour fournir plus d'informations sur la cause de l'erreur.

        • isError

          booléen

          Défini si l'erreur s'est produite du côté des outils de développement avant l'évaluation de l'expression.

        • isException

          booléen

          Défini si le code évalué génère une exception non gérée.

        • valeur

          chaîne

          Défini si le code évalué génère une exception non gérée.

      • résultat

        objet

        Résultat de l'évaluation.

Renvoie

  • Promise<object>

    Chrome 151 ou version ultérieure

    Fonction appelée une fois l'évaluation terminée.

    Les promesses ne sont compatibles qu'avec Manifest V3 et les versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

getResources()

Promise 
chrome.devtools.inspectedWindow.getResources(
  callback?: function,
): Promise<Resource[]>

Récupère la liste des ressources de la page inspectée.

Paramètres

  • callback

    function facultatif

    Le paramètre callback se présente comme suit : 

    (resources: Resource[]) => void

    • ressources

      Resource[]

      Ressources de la page.

Renvoie

  • // Promise<Resource[]>

    Chrome 151 ou version ultérieure

    Fonction qui reçoit la liste des ressources lorsque la requête est terminée.

    Les promesses ne sont compatibles qu'avec Manifest V3 et les versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

reload()

chrome.devtools.inspectedWindow.reload(
  reloadOptions?: object,
): void

Actualise la page inspectée.

Paramètres

  • reloadOptions

    objet facultatif

    • ignoreCache

      boolean facultatif

      Si la valeur est "true", le chargeur contourne le cache pour toutes les ressources de la page inspectée chargées avant le déclenchement de l'événement load. L'effet est semblable à celui d'une pression sur Ctrl+Maj+R dans la fenêtre inspectée ou dans la fenêtre des outils pour les développeurs.

    • injectedScript

      chaîne facultatif

      S'il est spécifié, le script sera injecté dans chaque frame de la page inspectée immédiatement après le chargement, avant tous les scripts du frame. Le script ne sera pas injecté après les actualisations ultérieures (par exemple, si l'utilisateur appuie sur Ctrl+R).

    • userAgent

      chaîne facultatif

      Si elle est spécifiée, la chaîne remplace la valeur de l'en-tête HTTP User-Agent envoyé lors du chargement des ressources de la page inspectée. La chaîne remplace également la valeur de la propriété navigator.userAgent renvoyée à tous les scripts exécutés sur la page inspectée.

Événements

onResourceAdded

chrome.devtools.inspectedWindow.onResourceAdded.addListener(
  callback: function,
)

Déclenché lorsqu'une nouvelle ressource est ajoutée à la page inspectée.

Paramètres

  • callback

    fonction

    Le paramètre callback se présente comme suit : 

    (resource: Resource) => void

onResourceContentCommitted

chrome.devtools.inspectedWindow.onResourceContentCommitted.addListener(
  callback: function,
)

Déclenché lorsqu'une nouvelle révision de la ressource est validée (par exemple, l'utilisateur enregistre une version modifiée de la ressource dans les outils pour les développeurs).

Paramètres

  • callback

    fonction

    Le paramètre callback se présente comme suit : 

    (resource: Resource, content: string) => void