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 qu'elle contient.
Manifest
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 qu'elle contient.
Consultez le résumé des API DevTools pour obtenir une présentation générale de l'utilisation des API Developer Tools.
Présentation
La propriété tabId
fournit l'identifiant de l'onglet que vous pouvez utiliser avec les appels d'API chrome.tabs.*
. Toutefois, veuillez noter que l'API chrome.tabs.*
n'est pas exposée aux pages de l'extension Outils pour les développeurs pour des raisons de sécurité. Vous devez transmettre l'ID d'onglet à la page en arrière-plan et appeler les fonctions de l'API chrome.tabs.*
à partir de celle-ci.
Vous pouvez utiliser la méthode reload
pour actualiser la page inspectée. En outre, l'appelant peut spécifier un forçage pour la chaîne user-agent, un script qui sera injecté tôt lors du chargement de la 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 le 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, et dangereuse lorsqu'elle est utilisée de manière inappropriée. Utilisez la méthode tabs.executeScript
, sauf si vous avez besoin des fonctionnalités spécifiques fournies 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 en cours d'évaluation. Par conséquent, le code peut accéder à l'état JavaScript de la fenêtre inspectée. Utilisez cette méthode lorsqu'un accès à l'état JavaScript de la page inspectée est requis. - Le contexte d'exécution du code évalué inclut l'API Developer Tools Console.
Par exemple, le code peut utiliser
inspect
et$0
. - Le code évalué peut renvoyer une valeur 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 vigilant lors du traitement des données provenant de la page inspectée. Le contexte d'exécution est principalement contrôlé par la page inspectée, et 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 a son propre contexte, plus 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
utilise 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 cadre autre que le cadre principal de la page inspectée.
contextSecurityOrigin
- Permet de sélectionner un contexte dans le frame 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 des extensions. (Équivaut à spécifier l'origine Web de l'extension en tant qu'origine de la sécurité du contexte.) Elle peut être utilisée pour échanger des données avec le script de contenu.
Exemples
Le code suivant permet de vérifier 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 de développement à partir du dépôt chrome-extension-samples.
Types
Resource
Ressource de la page inspectée, comme un document, un script ou une image.
Propriétés
-
url
chaîne
URL de la ressource.
-
getContent
void
Récupère le contenu de la ressource.
La fonction
getContent
se présente comme suit :(callback: function) => {...}
-
rappel
function
Le paramètre
callback
se présente comme suit :(content: string, encoding: string) => void
-
de qualité, inédits, adaptés et variés
chaîne
Contenu de la ressource (potentiellement encodé).
-
encoding
chaîne
Ce champ est vide si le contenu n'est pas encodé, et le nom de codage dans le cas contraire. Actuellement, seul le format base64 est accepté.
-
-
-
setContent
void
Définit le contenu de la ressource.
La fonction
setContent
se présente comme suit :(content: string, commit: boolean, callback?: function) => {...}
-
de qualité, inédits, adaptés et variés
chaîne
Nouveau contenu de la ressource. Seules les ressources de type texte sont actuellement acceptées.
-
valider
boolean
"True" si l'utilisateur a fini de modifier la ressource et que le nouveau contenu de la ressource doit être conservé ; "false" s'il s'agit d'une modification mineure en cours d'envoi par l'utilisateur en train de modifier la ressource.
-
rappel
fonction facultative
Le paramètre
callback
se présente comme suit :(error?: object) => void
-
error
objet facultatif
Défini sur "non défini" si le contenu de la ressource a bien été défini ; décrit l'erreur dans le cas contraire.
-
-
Propriétés
tabId
ID de l'onglet inspecté. Cet ID peut être utilisé avec chrome.tabs*. API.
Type
number
Méthodes
eval()
chrome.devtools.inspectedWindow.eval(
expression: string,
options?: object,
callback?: function,
)
Évalue une expression JavaScript dans le contexte du frame principal de la page inspectée. L'expression doit renvoyer un objet conforme au format JSON. Dans le cas contraire, une exception est générée. La fonction d'évaluation peut signaler une erreur côté outils de développement ou une exception JavaScript qui se produit pendant l'évaluation. Dans les deux cas, le paramètre result
du rappel est undefined
. Dans le cas d'une erreur côté outils de développement, le paramètre isException
n'est pas nul. isError
est défini sur "true" et code
sur un code d'erreur. Dans le cas d'une erreur JavaScript, isException
est défini sur "true" et value
est défini sur la valeur de chaîne de l'objet renvoyé.
Paramètres
-
expression
chaîne
Expression à évaluer.
-
options
objet facultatif
Le paramètre d'options peut contenir une ou plusieurs options.
-
frameURL
string 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 cadre supérieur de la page inspectée.
-
scriptExecutionContext
string facultatif
Chrome 107 et versions ultérieuresÉvalue l'expression dans le contexte d'un script de contenu d'une extension correspondant à l'origine spécifiée. S'il est défini, scriptExecutionContext remplace le paramètre "true" sur useContentScriptContext.
-
useContentScriptContext
Booléen 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 champcode
surE_NOTFOUND
.
-
-
rappel
fonction facultative
Le paramètre
callback
se présente comme suit :(result: object, exceptionInfo: object) => void
-
résultat
objet
Le résultat de l'évaluation
-
exceptionInfo
objet
Objet fournissant des détails si une exception s'est produite lors de l'évaluation de l'expression.
-
code
chaîne
Définit si l'erreur s'est produite du côté des outils de développement avant l'évaluation de l'expression.
-
description
chaîne
Définit si l'erreur s'est produite du côté des outils de développement avant l'évaluation de l'expression.
-
détails
tout[]
Définit si l'erreur s'est produite du côté des outils de développement avant l'évaluation de l'expression. Ce paramètre contient le tableau des valeurs pouvant être substituées dans la chaîne de description afin de fournir plus d'informations sur la cause de l'erreur.
-
isError
boolean
Définit si l'erreur s'est produite du côté des outils de développement avant l'évaluation de l'expression.
-
isException
boolean
Définissez ce paramètre si le code évalué génère une exception non gérée.
-
valeur
chaîne
Définissez ce paramètre si le code évalué génère une exception non gérée.
-
-
getResources()
chrome.devtools.inspectedWindow.getResources(
callback: function,
)
Récupère la liste des ressources de la page inspectée.
Paramètres
-
rappel
function
Le paramètre
callback
se présente comme suit :(resources: Resource[]) => void
-
ressources
Ressources sur la page.
-
reload()
chrome.devtools.inspectedWindow.reload(
reloadOptions?: object,
)
Il actualise la page inspectée.
Paramètres
-
reloadOptions
objet facultatif
-
ignoreCache
Booléen facultatif
Lorsque la valeur est "true", le chargeur ignore le cache pour toutes les ressources de la page inspectées et chargées avant le déclenchement de l'événement
load
. Cela revient à appuyer sur Ctrl+Maj+R dans la fenêtre inspectée ou dans la fenêtre des outils de développement. -
injectedScript
string facultatif
S'il est spécifié, le script est injecté dans chaque frame de la page inspectée immédiatement après le chargement, avant tous les scripts du frame. Le script n'est pas injecté après les rechargements suivants (par exemple, si l'utilisateur appuie sur Ctrl+R).
-
userAgent
string 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 en cours d'exécution 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
-
rappel
function
Le paramètre
callback
se présente comme suit :(resource: Resource) => void
-
ressource
-
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 de développement).