chrome.scripting

Description

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

Autorisations

scripting

Disponibilité

Chrome 88 et versions ultérieures MV3 et versions ultérieures

Fichier manifeste

Pour utiliser l'API chrome.scripting, déclarez l'autorisation "scripting" dans le 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'organisateur 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 chrome.scripting pour injecter du code JavaScript et CSS dans des sites Web. C'est un peu comme ce que vous pouvez faire avec les scripts de contenu. Toutefois, en utilisant l'espace de noms chrome.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() { ... }

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

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

function getTabId() { ... }

chrome.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 chrome.webNavigation.

function getTabId() { ... }

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

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() { ... }

chrome.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; }

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

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

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

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

Pour contourner ce problème, utilisez la propriété args :

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

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

Chaînes d'exécution

Si vous injectez du code 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 de chaîne à l'aide de scripting.executeScript().

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

chrome.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 frame. Le frame principal est garanti d'être le premier index du tableau résultant. Tous les autres frames sont dans un ordre non déterministe.

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

chrome.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ésultante 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;
}

chrome.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ésinscrire tous les scripts de contenu dynamique

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

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

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

Types

ContentScriptFilter

Chrome 96 et versions ultérieures

Propriétés

  • ids

    string[] facultatif

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

CSSInjection

Propriétés

  • css

    chaîne facultative

    Chaîne contenant le code CSS à injecter. Vous devez spécifier exactement une valeur pour files et css.

  • fichiers

    string[] facultatif

    Chemin d'accès aux fichiers CSS à injecter, relatif au répertoire racine de l'extension. Vous devez spécifier exactement une valeur pour files et css.

  • origin

    StyleOrigin facultatif

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

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

ExecutionWorld

Chrome 95 et versions ultérieures

Monde 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 JavaScript de la page hôte.

InjectionResult

Propriétés

  • documentId

    chaîne

    Chrome 106 et versions ultérieures

    Document associé à l'injection.

  • frameId

    Total

    Chrome 90 et versions ultérieures

    Frame associé à l'injection.

  • résultat

    tout facultatif

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

InjectionTarget

Propriétés

  • allFrames

    booléen 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

    Les ID des documentIds spécifiques à injecter. Cette valeur ne doit pas être définie si frameIds est défini.

  • frameIds

    number[] facultatif

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

  • tabId

    Total

    ID de l'onglet dans lequel injecter le contenu.

RegisteredContentScript

Chrome 96 et versions ultérieures

Propriétés

  • allFrames

    booléen facultatif

    Si la valeur est "true", l'injection se fera dans toutes les frames, même si la frame n'est pas la frame supérieure de l'onglet. Chaque frame est vérifié indépendamment en fonction des 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 seule la frame supérieure est mise 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 normalement 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 "_", car ce préfixe est réservé aux 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

    booléen facultatif

    Chrome 119 et versions ultérieures

    Indique si le script peut être injecté dans des frames dont l'URL contient un schéma non accepté, à savoir 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 de données), l'origine utilisée est soit le frame qui a créé le frame actuel, soit le frame qui a lancé la navigation vers ce frame. Notez qu'il ne s'agit pas forcément du frame parent.

  • correspond à

    string[] facultatif

    Indique 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

    booléen facultatif

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

  • runAt

    RunAt facultatif

    Indique quand les fichiers JavaScript sont injectés dans la page Web. La valeur par défaut et recommandée est document_idle.

  • monde

    ExecutionWorld facultatif

    Chrome 102 et versions ultérieures

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

ScriptInjection

Propriétés

  • args

    any[] facultatif

    Chrome 92 et versions ultérieures

    Arguments à transmettre à la fonction fournie. Cette valeur 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, relatif au répertoire racine de l'extension. Vous devez spécifier exactement l'un des éléments files ou func.

  • injectImmediately

    booléen facultatif

    Chrome 102 et versions ultérieures

    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 la page peut déjà être chargée au moment où le script atteint la cible.

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

  • monde

    ExecutionWorld facultatif

    Chrome 95 et versions ultérieures

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

  • func

    void optional

    Chrome 92 et versions ultérieures

    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 exactement l'un des éléments files ou func.

    La fonction func se présente comme suit : 

    () => {...}

StyleOrigin

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

Énumération

"AUTHOR"

"USER"

Méthodes

executeScript()

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

Injecte un script dans un contexte cible. Par défaut, le script s'exécute à 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 est évalué à une promesse, le navigateur attend que la promesse soit réglée et renvoie la valeur résultante.

Paramètres

Renvoie

getRegisteredContentScripts()

Chrome 96 et versions ultérieures 
chrome.scripting.getRegisteredContentScripts(
  filter?: ContentScriptFilter,
): Promise<RegisteredContentScript[]>

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

Paramètres

  • filtre

    ContentScriptFilter facultatif

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

Renvoie

insertCSS()

chrome.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

Renvoie

  • Promise<void>

    Chrome 90 et versions ultérieures

registerContentScripts()

Chrome 96 et versions ultérieures 
chrome.scripting.registerContentScripts(
  scripts: RegisteredContentScript[],
): Promise<void>

Enregistre un ou plusieurs scripts de contenu pour cette extension.

Paramètres

  • 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>

removeCSS()

Chrome 90 et versions ultérieures 
chrome.scripting.removeCSS(
  injection: CSSInjection,
): Promise<void>

Supprime une feuille de style CSS qui a été précédemment insérée par cette extension dans 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. Toute tentative de suppression d'une feuille de style inexistante est sans effet.

Renvoie

  • Promise<void>

unregisterContentScripts()

Chrome 96 et versions ultérieures 
chrome.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>

updateContentScripts()

Chrome 96 et versions ultérieures 
chrome.scripting.updateContentScripts(
  scripts: RegisteredContentScript[],
): Promise<void>

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

Paramètres

  • Contient une liste des 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>