tabs.executeScript()

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 cadres 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. La derniĂšre dĂ©claration peut Ă©galement ĂȘtre une Promise, mais cette fonctionnalitĂ© n'est pas supportĂ©e par la bibliothĂšque webextension-polyfill.
Si une erreur se produit, la promesse sera rejetĂ©e avec un message d’erreur.

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

Compatibilité des navigateurs

BCD tables only load in the browser

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.