browser.scripting

Description

Utilisez l'API chrome.scripting pour exécuter un script dans différents contextes.

Autorisations

scripting

Disponibilité

Navigateur Chrome 88 ou version ultérieure * depuis Chrome 148 MV3 ou version ultérieure

Fichier manifeste

Pour utiliser l'API browser.scripting, déclarez l'autorisation "scripting" dans le fichier manifeste, ainsi que les autorisations d'hôte pour les pages dans lesquelles injecter des scripts. Utilisez la clé "host_permissions" ou l'autorisation "activeTab", qui accorde des autorisations d'hôte temporaires. L'exemple suivant utilise l'autorisation activeTab.

{
  "name": "Scripting Extension",
  "manifest_version": 3,
  "permissions": ["scripting", "activeTab"],
  ...
}

Concepts et utilisation

Vous pouvez utiliser l'API browser.scripting pour injecter du code JavaScript et CSS dans des sites Web. Cela est semblable à ce que vous pouvez faire avec les scripts de contenu. Toutefois, en utilisant l'espace de noms browser.scripting, les extensions peuvent prendre des décisions au moment de l'exécution.

Cibles d'injection

Vous pouvez utiliser le paramètre target pour spécifier une cible dans laquelle injecter du code JavaScript ou CSS.

Le seul champ obligatoire est tabId. Par défaut, une injection s'exécute dans le frame principal de l'onglet spécifié.

function getTabId() { ... }

browser.scripting
    .executeScript({
      target : {tabId : getTabId()},
      files : [ "script.js" ],
    })
    .then(() => console.log("script injected"));

Pour l'exécuter dans toutes les frames de l'onglet spécifié, vous pouvez définir la valeur booléenne allFrames sur true.

function getTabId() { ... }

browser.scripting
    .executeScript({
      target : {tabId : getTabId(), allFrames : true},
      files : [ "script.js" ],
    })
    .then(() => console.log("script injected in all frames"));

Vous pouvez également injecter du code dans des frames spécifiques d'un onglet en spécifiant des ID de frame individuels. Pour en savoir plus sur les ID de frame, consultez l'API browser.webNavigation.

function getTabId() { ... }

browser.scripting
    .executeScript({
      target : {tabId : getTabId(), frameIds : [ frameId1, frameId2 ]},
      files : [ "script.js" ],
    })
    .then(() => console.log("script injected on target frames"));

Remarque : Vous ne pouvez pas spécifier à la fois les propriétés "frameIds" et "allFrames".

Code injecté

Les extensions peuvent spécifier le code à injecter via un fichier externe ou une variable d'exécution.

Fichiers

Les fichiers sont spécifiés sous forme de chaînes qui sont des chemins d'accès relatifs au répertoire racine de l'extension. Le code suivant injecte le fichier script.js dans le frame principal de l'onglet.

function getTabId() { ... }

browser.scripting
    .executeScript({
      target : {tabId : getTabId()},
      files : [ "script.js" ],
    })
    .then(() => console.log("injected script file"));

Fonctions d'exécution

Lorsque vous injectez du code JavaScript avec scripting.executeScript(), vous pouvez spécifier une fonction à exécuter au lieu d'un fichier. Cette fonction doit être une variable de fonction disponible pour le contexte d'extension actuel.

function getTabId() { ... }
function getTitle() { return document.title; }

browser.scripting
    .executeScript({
      target : {tabId : getTabId()},
      func : getTitle,
    })
    .then(() => console.log("injected a function"));

function getTabId() { ... }
function getUserColor() { ... }

function changeBackgroundColor() {
  document.body.style.backgroundColor = getUserColor();
}

browser.scripting
    .executeScript({
      target : {tabId : getTabId()},
      func : changeBackgroundColor,
    })
    .then(() => console.log("injected a function"));

Pour contourner ce problème, vous pouvez utiliser la propriété args :

function getTabId() { ... }
function getUserColor() { ... }
function changeBackgroundColor(backgroundColor) {
  document.body.style.backgroundColor = backgroundColor;
}

browser.scripting
    .executeScript({
      target : {tabId : getTabId()},
      func : changeBackgroundColor,
      args : [ getUserColor() ],
    })
    .then(() => console.log("injected a function"));

Chaînes d'exécution

Si vous injectez du CSS dans une page, vous pouvez également spécifier une chaîne à utiliser dans la propriété css. Cette option n'est disponible que pour scripting.insertCSS(). Vous ne pouvez pas exécuter une chaîne à l'aide de scripting.executeScript().

function getTabId() { ... }
const css = "body { background-color: red; }";

browser.scripting
    .insertCSS({
      target : {tabId : getTabId()},
      css : css,
    })
    .then(() => console.log("CSS injected"));

Gérer les résultats

Les résultats de l'exécution de JavaScript sont transmis à l'extension. Un seul résultat est inclus par image. Le frame principal est garanti d'être le premier index du tableau obtenu. Tous les autres frames sont dans un ordre non déterministe.

function getTabId() { ... }
function getTitle() { return document.title; }

browser.scripting
    .executeScript({
      target : {tabId : getTabId(), allFrames : true},
      func : getTitle,
    })
    .then(injectionResults => {
      for (const {frameId, result} of injectionResults) {
        console.log(`Frame ${frameId} result:`, result);
      }
    });

scripting.insertCSS() ne renvoie aucun résultat.

Promesses

Si la valeur résultant de l'exécution du script est une promesse, Chrome attendra que la promesse soit résolue et renverra la valeur résultante.

function getTabId() { ... }
async function addIframe() {
  const iframe = document.createElement("iframe");
  const loadComplete =
      new Promise(resolve => iframe.addEventListener("load", resolve));
  iframe.src = "https://example.com";
  document.body.appendChild(iframe);
  await loadComplete;
  return iframe.contentWindow.document.title;
}

browser.scripting
    .executeScript({
      target : {tabId : getTabId(), allFrames : true},
      func : addIframe,
    })
    .then(injectionResults => {
      for (const frameResult of injectionResults) {
        const {frameId, result} = frameResult;
        console.log(`Frame ${frameId} result:`, result);
      }
    });

Exemples

Désenregistrer tous les scripts de contenu dynamique

L'extrait de code suivant contient une fonction qui annule l'enregistrement de tous les scripts de contenu dynamique que l'extension a précédemment enregistrés.

async function unregisterAllDynamicContentScripts() {
  try {
    const scripts = await browser.scripting.getRegisteredContentScripts();
    const scriptIds = scripts.map(script => script.id);
    return browser.scripting.unregisterContentScripts({ ids: scriptIds });
  } catch (error) {
    const message = [
      "An unexpected error occurred while",
      "unregistering dynamic content scripts.",
    ].join(" ");
    throw new Error(message, {cause : error});
  }
}

Point clé : La désinscription des scripts de contenu ne supprime pas les scripts ou les styles qui ont déjà été injectés.

Pour essayer l'API browser.scripting, installez l'exemple de script à partir du dépôt d'exemples d'extensions Chrome.

Types

ContentScriptFilter

Chrome 96+ browser.* depuis Chrome 148

Propriétés

• ids

  string[] facultatif

  Si spécifié, getRegisteredContentScripts ne renverra que les scripts dont l'ID est spécifié dans cette liste.

CSSInjection

Propriétés

• css

  chaîne facultatif

  Chaîne contenant le code CSS à injecter. Vous devez spécifier soit files, soit css.

• fichiers

  string[] facultatif

  Chemin d'accès aux fichiers CSS à injecter, par rapport au répertoire racine de l'extension. Vous devez spécifier soit files, soit css.

• origin

  StyleOrigin facultatif

  Origine du style pour l'injection. La valeur par défaut est 'AUTHOR'.

• cible

  InjectionTarget

  Détails spécifiant la cible dans laquelle insérer le CSS.

ExecutionWorld

Chrome 95 et versions ultérieures browser.* depuis Chrome 148

Environnement JavaScript dans lequel un script doit s'exécuter.

Énumération

"ISOLATED"
Spécifie le monde isolé, qui est l'environnement d'exécution propre à cette extension.

"MAIN"
Spécifie le monde principal du DOM, qui est l'environnement d'exécution partagé avec le code JavaScript de la page hôte.

InjectionResult

Propriétés

• documentId

  chaîne

  Chrome 106 et versions ultérieures browser.* depuis Chrome 148

  Document associé à l'injection.

• frameId

  nombre

  Chrome 90+ browser.* depuis Chrome 148

  Le frame associé à l'injection.

• résultat

  facultatif

  Résultat de l'exécution du script.

InjectionTarget

Propriétés

• allFrames

  boolean facultatif

  Indique si le script doit être injecté dans toutes les frames de l'onglet. Valeur par défaut : "false". Cette valeur ne doit pas être "true" si frameIds est spécifié.

• documentIds

  string[] facultatif

  Chrome 106 et versions ultérieures browser.* depuis Chrome 148

  ID des documentIds spécifiques dans lesquels injecter. Ce champ ne doit pas être défini si frameIds est défini.

• frameIds

  number[] facultatif

  ID des frames spécifiques dans lesquels injecter le script.

• tabId

  nombre

  ID de l'onglet dans lequel injecter.

RegisteredContentScript

Chrome 96+ browser.* depuis Chrome 148

Propriétés

• allFrames

  boolean facultatif

  Si la valeur est "true", l'injection s'effectue dans tous les cadres, même s'il ne s'agit pas du cadre le plus haut de l'onglet. Chaque frame est vérifié indépendamment pour les exigences relatives aux URL. Il ne sera pas injecté dans les frames enfants si les exigences relatives aux URL ne sont pas respectées. La valeur par défaut est "false", ce qui signifie que seul le frame supérieur est mis en correspondance.

• css

  string[] facultatif

  Liste des fichiers CSS à injecter dans les pages correspondantes. Ils sont injectés dans l'ordre dans lequel ils apparaissent dans ce tableau, avant que le DOM ne soit construit ou affiché pour la page.

• excludeMatches

  string[] facultatif

  Exclut les pages dans lesquelles ce script de contenu serait injecté. Pour en savoir plus sur la syntaxe de ces chaînes, consultez Formats de correspondance.

• id

  chaîne

  ID du script de contenu, spécifié dans l'appel d'API. Ne doit pas commencer par un trait de soulignement (_), car il est réservé comme préfixe pour les ID de script générés.

• js

  string[] facultatif

  Liste des fichiers JavaScript à injecter dans les pages correspondantes. Ils sont injectés dans l'ordre dans lequel ils apparaissent dans ce tableau.

• matchOriginAsFallback

  boolean facultatif

  Chrome 119 et versions ultérieures browser.* depuis Chrome 148

  Indique si le script peut être injecté dans des frames dont l'URL contient un schéma non compatible, en particulier : about:, data:, blob: ou filesystem:. Dans ce cas, l'origine de l'URL est vérifiée pour déterminer si le script doit être injecté. Si l'origine est null (comme c'est le cas pour les URL data:), l'origine utilisée est soit le frame qui a créé le frame actuel, soit le frame qui a initié la navigation vers ce frame. Notez qu'il ne s'agit pas nécessairement du frame parent.

• correspond à

  string[] facultatif

  Spécifie les pages dans lesquelles ce script de contenu sera injecté. Pour en savoir plus sur la syntaxe de ces chaînes, consultez Formats de correspondance. Doit être spécifié pour registerContentScripts.

• persistAcrossSessions

  boolean facultatif

  Indique si ce script de contenu sera conservé dans les sessions futures. La valeur par défaut est "true".

• runAt

  RunAt facultatif

  Spécifie quand les fichiers JavaScript sont injectés dans la page Web. La valeur par défaut et préférée est document_idle.

• monde

  ExecutionWorld facultatif

  Navigateur Chrome 102 ou version ultérieure * depuis Chrome 148

  "Monde" JavaScript dans lequel exécuter le script. La valeur par défaut est ISOLATED.

ScriptInjection

Propriétés

• args

  any[] facultatif

  Chrome 92+ browser.* depuis Chrome 148

  Arguments à transmettre à la fonction fournie. Cette option n'est valide que si le paramètre func est spécifié. Ces arguments doivent être sérialisables en JSON.

• fichiers

  string[] facultatif

  Chemin d'accès aux fichiers JS ou CSS à injecter, par rapport au répertoire racine de l'extension. Vous devez spécifier soit files, soit func.

• injectImmediately

  boolean facultatif

  Navigateur Chrome 102 ou version ultérieure * depuis Chrome 148

  Indique si l'injection doit être déclenchée dans la cible dès que possible. Notez que cela ne garantit pas que l'injection aura lieu avant le chargement de la page, car celle-ci peut déjà avoir été chargée au moment où le script atteint la cible.

• cible

  InjectionTarget

  Détails spécifiant la cible dans laquelle injecter le script.

• monde

  ExecutionWorld facultatif

  Chrome 95 et versions ultérieures browser.* depuis Chrome 148

  "Monde" JavaScript dans lequel exécuter le script. La valeur par défaut est ISOLATED.

• func

  void facultatif

  Chrome 92+ browser.* depuis Chrome 148

  Fonction JavaScript à injecter. Cette fonction sera sérialisée, puis désérialisée pour l'injection. Cela signifie que tous les paramètres liés et le contexte d'exécution seront perdus. Vous devez spécifier soit files, soit func.

  La fonction func se présente comme suit :

  () => {...}

StyleOrigin

Origine d'un changement de style. Pour en savoir plus, consultez Origines des styles.

Énumération

"AUTEUR"

"USER"

Méthodes

executeScript()

browser.scripting.executeScript(
  injection: ScriptInjection,
): Promise<InjectionResult[]>

Injecte un script dans un contexte cible. Par défaut, le script est exécuté à document_idle, ou immédiatement si la page est déjà chargée. Si la propriété injectImmediately est définie, le script sera injecté sans attendre, même si la page n'a pas fini de se charger. Si le script renvoie une promesse, le navigateur attendra que la promesse soit résolue et renverra la valeur obtenue.

Paramètres

• Injection

  ScriptInjection

  Détails du script à injecter.

Renvoie

• Promise<InjectionResult[]>

  Chrome 90+ browser.* depuis Chrome 148

  Renvoie une promesse qui se résout une fois l'injection terminée. Le tableau obtenu contient le résultat de l'exécution pour chaque frame où l'injection a réussi.

getRegisteredContentScripts()

Chrome 96+ browser.* depuis Chrome 148

browser.scripting.getRegisteredContentScripts(
  filter?: ContentScriptFilter,
): Promise<RegisteredContentScript[]>

Renvoie tous les scripts de contenu enregistrés de manière dynamique pour cette extension qui correspondent au filtre donné.

Paramètres

• filtre

  ContentScriptFilter facultatif

  Objet permettant de filtrer les scripts enregistrés de manière dynamique de l'extension.

Renvoie

• Promise<RegisteredContentScript[]>

insertCSS()

browser.scripting.insertCSS(
  injection: CSSInjection,
): Promise<void>

Insère une feuille de style CSS dans un contexte cible. Si plusieurs frames sont spécifiés, les injections infructueuses sont ignorées.

Paramètres

• Injection

  CSSInjection

  Détails des styles à insérer.

Renvoie

• Promise<void>

  Chrome 90+ browser.* depuis Chrome 148

  Renvoie une promesse qui se résout une fois l'insertion terminée.

registerContentScripts()

Chrome 96+ browser.* depuis Chrome 148

browser.scripting.registerContentScripts(
  scripts: RegisteredContentScript[],
): Promise<void>

Enregistre un ou plusieurs scripts de contenu pour cette extension.

Paramètres

• scripts

  RegisteredContentScript[]

  Contient une liste de scripts à enregistrer. Si des erreurs se produisent lors de l'analyse du script ou de la validation du fichier, ou si les ID spécifiés existent déjà, aucun script n'est enregistré.

Renvoie

• Promise<void>

  Renvoie une promesse qui se résout une fois que les scripts ont été entièrement enregistrés ou qui est rejetée si une erreur s'est produite.

removeCSS()

Chrome 90+ browser.* depuis Chrome 148

browser.scripting.removeCSS(
  injection: CSSInjection,
): Promise<void>

Supprime une feuille de style CSS précédemment insérée par cette extension à partir d'un contexte cible.

Paramètres

• Injection

  CSSInjection

  Détails des styles à supprimer. Notez que les propriétés css, files et origin doivent correspondre exactement à la feuille de style insérée via insertCSS. La tentative de suppression d'une feuille de style inexistante est sans effet.

Renvoie

• Promise<void>

  Renvoie une promesse qui se résout une fois la suppression terminée.

unregisterContentScripts()

Chrome 96+ browser.* depuis Chrome 148

browser.scripting.unregisterContentScripts(
  filter?: ContentScriptFilter,
): Promise<void>

Annule l'enregistrement des scripts de contenu pour cette extension.

Paramètres

• filtre

  ContentScriptFilter facultatif

  Si cette option est spécifiée, seuls les scripts de contenu dynamique correspondant au filtre sont désenregistrés. Sinon, tous les scripts de contenu dynamique de l'extension sont désenregistrés.

Renvoie

• Promise<void>

  Renvoie une promesse qui se résout une fois que l'enregistrement des scripts a été annulé ou qui est rejetée si une erreur s'est produite.

updateContentScripts()

Chrome 96+ browser.* depuis Chrome 148

browser.scripting.updateContentScripts(
  scripts: RegisteredContentScript[],
): Promise<void>

Met à jour un ou plusieurs scripts de contenu pour cette extension.

Paramètres

• scripts

  RegisteredContentScript[]

  Contient une liste de scripts à mettre à jour. Une propriété n'est mise à jour pour le script existant que si elle est spécifiée dans cet objet. Si des erreurs se produisent lors de l'analyse du script ou de la validation du fichier, ou si les ID spécifiés ne correspondent pas à un script entièrement enregistré, aucun script n'est mis à jour.

Renvoie

• Promise<void>

  Renvoie une promesse qui se résout une fois que les scripts ont été mis à jour ou qui est rejetée si une erreur s'est produite.