Injecte du code JavaScript dans une page.

Vous pouvez injecter du code dans des pages dont l'URL peut être exprimée à l'aide d'un modèle de correspondance : son schéma doit être "http", "https", "file", "ftp". Pour ce faire, vous devez disposer de la permission pour l'URL de la page, soit explicitement en tant que permission d'hôte, ou via la permission activeTab.

Vous pouvez également injecter du code dans des pages empaquetées avec votre propre extension :

browser.tabs.create({url: "/my-page.html"}).then(() => {
  browser.tabs.executeScript({
    code: `console.log('location:', window.location.href);`
  });
});

Vous n'avez pas besoin de permissions spéciales pour le faire.

Vous ne pouvez pas injecter de code dans les pages intégrées du navigateur, par exemple : about:debugging, about:addons, ou sur la page qui s'ouvre lorsque vous ouvrez un nouvel onglet vide.

Les scripts que vous injectez s’appellent des scripts de contenu. En savoir plus sur les scripts de contenu.

Il s’agit d’une fonction asynchrone qui renvoie une Promise.

Syntaxe

var executing = browser.tabs.executeScript(
  tabId,                 // optional integer
  details                // object
)

Paramètres

tabId Facultatif
integer. L’ID de l’onglet dans lequel exécuter le script. Par défaut, l’onglet actif de la fenêtre en cours.
details
Un objet décrivant le script à exécuter. Il contient les propriétés suivantes :
allFrames Facultatif
boolean. Si true, le code sera injecté dans toutes les images de la page courante. Si true et frameId est défini, alors il y aura une erreur, frameId et allFrames sont mutuellement exclusifs. Si c'est false, le code n'est injecté que dans le cadre supérieur. La valeur par défaut est false.
code Facultatif
string. Code à injecter, sous la forme d’une chaine de texte. Attention : n’utilisez pas cette propriété pour interpoler des données non sûres dans JavaScript, car cela pourrait introduire une faille de sécurité.
file Facultatif
string. Chemin d’accès à un fichier contenant le code à injecter. Dans Firefox, les URL relatives ne commençant pas à la racine de l'extension sont résolues par rapport à l'URL de la page en cours. Dans Chrome, ces URL sont résolues par rapport à l’URL de base de l’extension. Pour travailler avec plusieurs navigateurs, vous pouvez spécifier le chemin comme une URL relative, en commençant à la racine de l’extension, comme ceci : "/path/to/script.js".
frameId Facultatif
integer. Le cadre où le code doit être injecté. La valeur par défaut est 0 (le cadre de niveau supérieur).
matchAboutBlank Facultatif
boolean. Si true, le code sera injecté dans des cadres about:blank et about:srcdoc inclus depuis une page si votre extension a accès à leur document parent. Le code ne peut pas être inséré dans les cadres about: de niveau supérieur. Par défaut, false.
runAt Facultatif
extensionTypes.RunAt. Le moment le plus tôt auquel le code sera injecté dans l’onglet. Par défaut, document_idle.

Valeur de retour

Une Promise résolue avec un tableau d’objets représentant le résultat du script dans chaque cadre où le script a été injecté.

Le résultat du script est la dernière instruction évaluée, ce qui est similaire à ce qui serait produit (les résultats, pas les affichages de console.log()) si vous exécutiez le script dans la Console Web. Par exemple, considérez un script comme celui-ci :

var foo='my result';foo;

Ici, le tableau des résultats contiendra la chaîne "my result" en tant qu’élément. Les valeurs de résultat doivent être clonables tructurées.

Si une erreur se produit, la promesse sera rejetée avec un message d’erreur.

Compatibilité des navigateurs

Update compatibility data on GitHub
OrdinateurMobile
ChromeEdgeFirefoxOperaFirefox pour Android
Support simpleChrome Support complet Oui
Notes
Support complet Oui
Notes
Notes Extensions can't inject scripts into their own pages using this API.
Edge Support complet 14Firefox Support complet 43
Notes
Support complet 43
Notes
Notes Before version 50, Firefox would pass a single result value into its callback rather than an array, unless 'allFrames' had been set.
Opera Support complet Oui
Notes
Support complet Oui
Notes
Notes Extensions can't inject scripts into their own pages using this API.
Firefox Android Support complet 54
runAtChrome Support complet 20Edge Aucun support NonFirefox Support complet 43Opera Support complet 15Firefox Android Support complet 54
frameIdChrome Support complet 39Edge Aucun support NonFirefox Support complet 43
Notes
Support complet 43
Notes
Notes 'allFrames' and 'frameId' can't both be set at the same time.
Opera Support complet 26Firefox Android Support complet 54
Notes
Support complet 54
Notes
Notes 'allFrames' and 'frameId' can't both be set at the same time.
matchAboutBlankChrome Support complet 39Edge Support complet 14Firefox Support complet 53Opera Support complet 26Firefox Android Support complet 54

Légende

Support complet  
Support complet
Aucun support  
Aucun support
Voir les notes d'implémentation.
Voir les notes d'implémentation.

Exemples

Cet exemple exécute un extrait de code d’une ligne dans l’onglet actuellement actif :

function onExecuted(result) {
  console.log(`We made it green`);
}

function onError(error) {
  console.log(`Error: ${error}`);
}

var makeItGreen = 'document.body.style.border = "5px solid green"';

var executing = browser.tabs.executeScript({
  code: makeItGreen
});
executing.then(onExecuted, onError);

L’exemple suivant exécute un script à partir d’un fichier empaqueté avec l’extension appelé content-script.js. Le script est exécuté dans l’onglet actuellement actif. Le script est exécuté dans les sous-cadres ainsi que dans le document principal :

function onExecuted(result) {
  console.log(`We executed in all subframes`);
}

function onError(error) {
  console.log(`Error: ${error}`);
}

var executing = browser.tabs.executeScript({
  file: "/content-script.js",
  allFrames: true
});
executing.then(onExecuted, onError);

L’exemple suivant exécute un script à partir d’un fichier empaqueté avec l’extension appelé content-script.js. Le script est exécuté dans l’onglet ayant l’ID 2 :

function onExecuted(result) {
  console.log(`We executed in tab 2`);
}

function onError(error) {
  console.log(`Error: ${error}`);
}

var executing = browser.tabs.executeScript(
  2, {
    file: "/content-script.js"
});
executing.then(onExecuted, onError);

Example extensions

Remerciements :

Cette API est basée sur l’API chrome.tabs de Chromium. Cette documentation est dérivée de tabs.json dans le code de Chromium code.

Étiquettes et contributeurs liés au document

Contributeurs à cette page : hellosct1, Watilin
Dernière mise à jour par : hellosct1,