chrome.scripting

Description

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

Autorisations

scripting

Disponibilité

Chrome 88 ou version ultérieure MV3+

Fichier manifeste

Pour utiliser l'API chrome.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 chrome.scripting pour injecter du code JavaScript et CSS dans sites Web. Ceci est similaire à ce que vous pouvez faire avec du contenu scripts. 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 est exécutée 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 l'exécuter dans tous les frames de l'onglet spécifié, vous pouvez définir la valeur booléenne allFrames à 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 dans des frames spécifiques d'un onglet en spécifiant des frames individuels ID. Pour en savoir plus sur les ID de cadre, consultez le chrome.webNavigation API.

function getTabId() { ... }

chrome.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 soit via un fichier externe, variable d'exécution.

Fichiers

Les fichiers sont spécifiés en tant que chaînes, qui sont des chemins relatifs à la racine de l'extension . Le code suivant injecte le fichier script.js dans cadre 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 un à exécuter au lieu d'un fichier. Cette fonction doit être une 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 css. Cette option n'est disponible que pour scripting.insertCSS(). vous ne peut pas exécuter une 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 image. Le frame principal est assuré d'être le premier index du tableau résultant; toutes les autres trames 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 pour la promesse de régler et de renvoyer 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

Annuler l'enregistrement de tous les scripts de contenu dynamique

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

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

Important:L'annulation de l'enregistrement de scripts de contenu n'entraîne pas la suppression des scripts ou des styles qui comportent déjà été injectées.

Pour essayer l'API chrome.scripting, procédez comme suit : Installez l'exemple de script à partir des exemples d'extension Chrome un dépôt de clés.

Types

ContentScriptFilter

Chrome 96 ou version ultérieure

Propriétés

• ids

  string[] facultatif

  Si cette option 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 facultatif

  Chaîne contenant le CSS à injecter. Vous ne devez spécifier qu'un seul des champs files et css.

• fichiers

  string[] facultatif

  Chemin des fichiers CSS à injecter, relatif au répertoire racine de l'extension. Vous ne devez spécifier qu'un seul des champs files et css.

• origine

  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 ou version ultérieure

L'univers 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 l'environnement principal du DOM, qui correspond à 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

  Nombre

  Chrome 90 ou version ultérieure

  La trame associée à 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 injecter dans tous les frames de l'onglet. Valeur par défaut : "false". Ne doit pas être "true" si frameIds est spécifié.

• documentIds

  string[] facultatif

  Chrome 106 et versions ultérieures

  ID des ID de document spécifiques dans lesquels injecter. Ne doit pas être défini si frameIds est défini.

• frameIds

  number[] facultatif

  ID des frames spécifiques à injecter.

• tabId

  Nombre

  ID de l'onglet dans lequel injecter.

RegisteredContentScript

Chrome 96 ou version ultérieure

Propriétés

• allFrames

  Booléen facultatif

  Si la valeur est "true", les images sont injectées dans tous les cadres, même si ceux-ci ne sont pas situés en haut de l'onglet. Les exigences relatives aux URL sont vérifiées indépendamment pour chaque frame. il n'est pas injecté dans les frames enfants si les exigences de l'URL ne sont pas remplies. La valeur par défaut est "false", ce qui signifie que seule l'image du haut correspond.

• 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 qu'un DOM ne soit construit ou affiché pour la page.

• excludeMatches

  string[] facultatif

  Exclut les pages dans lesquelles ce script de contenu serait autrement injecté. Consultez la section Formats de correspondance pour en savoir plus sur la syntaxe de ces chaînes.

• id

  chaîne

  ID du script de contenu, spécifié dans l'appel d'API. L'ID ne doit pas commencer par le caractère "_" 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. Celles-ci sont injectées dans l'ordre dans lequel elles apparaissent dans le 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 pris en charge. en particulier: about:, data:, blob: ou système de fichiers:. 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 "data: URL"), l'origine utilisée est soit le frame qui a créé le frame actuel, soit celui qui a initié la navigation vers ce frame. Notez qu'il ne s'agit peut-être pas du cadre parent.

• correspond à

  string[] facultatif

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

• persistAcrossSessions

  Booléen facultatif

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

• runAt

  RunAt facultatif

  Indique à quel moment les fichiers JavaScript sont injectés dans la page Web. La valeur préférée par défaut est document_idle.

• monde

  ExecutionWorld facultatif

  Chrome 102 et versions ultérieures

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

ScriptInjection

Propriétés

• args

  any[] facultatif

  Chrome 92 ou version ultérieure

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

• fichiers

  string[] facultatif

  Chemin des fichiers JS ou CSS à injecter, relatif au répertoire racine de l'extension. Vous ne devez spécifier qu'une seule propriété 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 se produira 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 ou version ultérieure

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

• func

  vide facultatif

  Chrome 92 ou version ultérieure

  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 ne devez spécifier qu'une seule propriété files ou func.

  La fonction func se présente comme suit:

  () => {...}

StyleOrigin

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

Énumération

"AUTHOR"

"USER"

Méthodes

executeScript()

<ph type="x-smartling-placeholder"></ph> Promesse

chrome.scripting.executeScript(
  injection: ScriptInjection,
  callback?: function,
)

Injecte un script dans un contexte cible. Par défaut, le script s'exécutera à document_idle ou immédiatement si la page est déjà chargée. Si la propriété injectImmediately est définie, le script est injecté sans attendre, même si le chargement de la page n'est pas terminé. Si le script renvoie une promesse, le navigateur attend que la promesse se satisfasse et renvoie la valeur résultante.

Paramètres

• Injection

  ScriptInjection

  Détails du script à injecter.

• rappel

  function facultatif

  Le paramètre callback se présente comme suit:

  (results: InjectionResult[]) => void

  • résultats

    InjectionResult[]

Renvoie

• Promise&lt;InjectionResult[]&gt;

  Chrome 90 ou version ultérieure

  Les promesses sont prises en charge dans Manifest V3 et versions ultérieures, mais les rappels sont fournis pour rétrocompatibilité. Vous ne pouvez pas utiliser les deux sur le même appel de fonction. La la promesse est résolue avec le même type que celui transmis au rappel.

getRegisteredContentScripts()

<ph type="x-smartling-placeholder"></ph> Promesse Chrome 96 ou version ultérieure

chrome.scripting.getRegisteredContentScripts(
  filter?: ContentScriptFilter,
  callback?: function,
)

Renvoie tous les scripts de contenu enregistrés dynamiquement pour cette extension qui correspondent au filtre donné.

Paramètres

• filtre

  ContentScriptFilter facultatif

  Objet permettant de filtrer les scripts enregistrés dynamiquement de l'extension.

• rappel

  function facultatif

  Le paramètre callback se présente comme suit:

  (scripts: RegisteredContentScript[]) => void

  • scripts

    RegisteredContentScript[]

Renvoie

• Promise&lt;RegisteredContentScript[]&gt;

  Les promesses sont prises en charge dans Manifest V3 et versions ultérieures, mais les rappels sont fournis pour rétrocompatibilité. Vous ne pouvez pas utiliser les deux sur le même appel de fonction. La la promesse est résolue avec le même type que celui transmis au rappel.

insertCSS()

<ph type="x-smartling-placeholder"></ph> Promesse

chrome.scripting.insertCSS(
  injection: CSSInjection,
  callback?: function,
)

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.

• rappel

  function facultatif

  Le paramètre callback se présente comme suit:

  () => void

Renvoie

• Promesse<void>

  Chrome 90 ou version ultérieure

  Les promesses sont prises en charge dans Manifest V3 et versions ultérieures, mais les rappels sont fournis pour rétrocompatibilité. Vous ne pouvez pas utiliser les deux sur le même appel de fonction. La la promesse est résolue avec le même type que celui transmis au rappel.

registerContentScripts()

<ph type="x-smartling-placeholder"></ph> Promesse Chrome 96 ou version ultérieure

chrome.scripting.registerContentScripts(
  scripts: RegisteredContentScript[],
  callback?: function,
)

Enregistre un ou plusieurs scripts de contenu pour cette extension.

Paramètres

• scripts

  RegisteredContentScript[]

  Contient la liste des 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é.

• rappel

  function facultatif

  Le paramètre callback se présente comme suit:

  () => void

Renvoie

• Promesse<void>

  Les promesses sont prises en charge dans Manifest V3 et versions ultérieures, mais les rappels sont fournis pour rétrocompatibilité. Vous ne pouvez pas utiliser les deux sur le même appel de fonction. La la promesse est résolue avec le même type que celui transmis au rappel.

removeCSS()

<ph type="x-smartling-placeholder"></ph> Promesse Chrome 90 ou version ultérieure

chrome.scripting.removeCSS(
  injection: CSSInjection,
  callback?: function,
)

Supprime une feuille de style CSS 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 impossible.

• rappel

  function facultatif

  Le paramètre callback se présente comme suit:

  () => void

Renvoie

• Promesse<void>

  Les promesses sont prises en charge dans Manifest V3 et versions ultérieures, mais les rappels sont fournis pour rétrocompatibilité. Vous ne pouvez pas utiliser les deux sur le même appel de fonction. La la promesse est résolue avec le même type que celui transmis au rappel.

unregisterContentScripts()

<ph type="x-smartling-placeholder"></ph> Promesse Chrome 96 ou version ultérieure

chrome.scripting.unregisterContentScripts(
  filter?: ContentScriptFilter,
  callback?: function,
)

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

Paramètres

• filtre

  ContentScriptFilter facultatif

  Si cette valeur est spécifiée, seuls les scripts de contenu dynamique qui correspondent au filtre sont annulés. Sinon, l'enregistrement de tous les scripts de contenu dynamique de l'extension est annulé.

• rappel

  function facultatif

  Le paramètre callback se présente comme suit:

  () => void

Renvoie

• Promesse<void>

  Les promesses sont prises en charge dans Manifest V3 et versions ultérieures, mais les rappels sont fournis pour rétrocompatibilité. Vous ne pouvez pas utiliser les deux sur le même appel de fonction. La la promesse est résolue avec le même type que celui transmis au rappel.

updateContentScripts()

<ph type="x-smartling-placeholder"></ph> Promesse Chrome 96 ou version ultérieure

chrome.scripting.updateContentScripts(
  scripts: RegisteredContentScript[],
  callback?: function,
)

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

Paramètres

• scripts

  RegisteredContentScript[]

  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.

• rappel

  function facultatif

  Le paramètre callback se présente comme suit:

  () => void

Renvoie

• Promesse<void>

  Les promesses sont prises en charge dans Manifest V3 et versions ultérieures, mais les rappels sont fournis pour rétrocompatibilité. Vous ne pouvez pas utiliser les deux sur le même appel de fonction. La la promesse est résolue avec le même type que celui transmis au rappel.