Description
Utilisez l'API chrome.scripting
pour exécuter le script dans différents contextes.
Autorisations
scripting
Garantie de disponibilité
Manifest
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"
pour accorder 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 des sites Web. Ce processus est semblable à celui des 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 sera 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 s'exécuter dans tous les frames de l'onglet spécifié, vous pouvez définir la valeur booléenne 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 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 en tant que chaînes. Il s'agit de chemins relatifs au répertoire racine de l'extension. Le code suivant injecte le fichier script.js
dans le cadre 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 à la place d'un fichier. Il doit s'agir d'une variable de fonction disponible dans 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 avec 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. L'image principale sera forcément 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ésultant de l'exécution du script est une promesse, Chrome attend que la promesse se stabilise et renvoie la valeur obtenue.
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 tous les scripts de contenu dynamique enregistrés précédemment par l'extension.
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});
}
}
Pour essayer l'API chrome.scripting
, installez l'exemple de script à partir du dépôt des exemples d'extensions Chrome.
Types
ContentScriptFilter
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
string facultatif
Chaîne contenant le code CSS à injecter. Vous ne devez spécifier qu'une seule des propriétés suivantes :
files
etcss
. -
files
string[] facultatif
Chemin d'accès aux fichiers CSS à injecter, par rapport au répertoire racine de l'extension. Vous ne devez spécifier qu'une seule des propriétés suivantes :
files
etcss
. -
origine
StyleOrigin facultatif
Origine du style pour l'injection. La valeur par défaut est
'AUTHOR'
. -
cible
Informations spécifiant la cible dans laquelle insérer le CSS
ExecutionWorld
Monde JavaScript dans lequel un script doit s'exécuter.
Enum
"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érieuresDocument associé à l'injection.
-
frameId
number
Chrome 90 et versions ultérieuresFrame associé à l'injection.
-
résultat
Toute valeur 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 tous les frames de l'onglet. Valeur par défaut : "false". Cette valeur ne doit pas être vraie si
frameIds
est spécifié. -
documentIds
string[] facultatif
Chrome 106 et versions ultérieuresLes ID des documentId spécifiques dans lesquels injecter le code. 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
number
ID de l'onglet dans lequel effectuer l'injection.
RegisteredContentScript
Propriétés
-
allFrames
Booléen facultatif
Si la valeur est "true", l'insertion est effectuée dans tous les frames, même s'ils ne se trouvent pas dans le cadre supérieur de l'onglet. Chaque image est vérifiée indépendamment pour les exigences d'URL. Elle n'est pas injectée dans les frames enfants si les exigences d'URL ne sont pas remplies. La valeur par défaut est "false", ce qui signifie que seule le cadre supérieur est mis en correspondance.
-
css
string[] facultatif
Liste des fichiers CSS à injecter dans les pages correspondantes. Ceux-ci sont injectés dans l'ordre dans lequel ils apparaissent dans ce tableau, avant la construction ou l'affichage de tout DOM sur la page.
-
excludeMatches
string[] facultatif
Exclut les pages dans lesquelles ce script de contenu serait autrement injecté. Consultez 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. Ne doit pas commencer par "_", 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. Ces éléments sont injectés dans l'ordre dans lequel ils apparaissent dans ce tableau.
-
matchOriginAsFallback
Booléen facultatif
Chrome 119 et versions ultérieuresIndique si le script peut être injecté dans des frames dont l'URL contient un schéma non compatible, à 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 données: URL), 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 peut s'agir pas du frame parent. -
correspondances
string[] facultatif
Spécifie les pages dans lesquelles ce script de contenu sera injecté. Consultez 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 sera conservé dans les sessions futures. La valeur par défaut est "true".
-
runAt
RunAt facultatif
Indique à quel moment des fichiers JavaScript sont injectés dans la page Web. La valeur par défaut est
document_idle
. -
international
ExecutionWorld facultatif
Chrome 102 et versions ultérieuresLe "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érieuresArguments à transmettre à la fonction fournie. Ce champ n'est valide que si le paramètre
func
est spécifié. Ces arguments doivent être sérialisables au format JSON. -
files
string[] facultatif
Chemin des fichiers JS ou CSS à injecter, par rapport au répertoire racine de l'extension. Vous ne devez spécifier qu'une seule des options
files
oufunc
. -
injectImmediately
Booléen facultatif
Chrome 102 et versions ultérieuresIndique 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 aura peut-être déjà été chargée au moment où le script aura atteint la cible.
-
cible
Détails indiquant la cible dans laquelle injecter le script
-
international
ExecutionWorld facultatif
Chrome 95 et versions ultérieuresLe "monde" JavaScript dans lequel exécuter le script. La valeur par défaut est
ISOLATED
. -
func
vide facultatif
Chrome 92 et versions ultérieuresFonction JavaScript à injecter. Cette fonction sera sérialisée, puis désérialisée pour 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 des options
files
oufunc
.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.
Enum
"AUTHOR"
Méthodes
executeScript()
chrome.scripting.executeScript(
injection: ScriptInjection,
callback?: function,
)
Injecte un script dans un contexte cible. Par défaut, le script est exécuté sur 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 le chargement de la page n'est pas terminé. Si le script évalue une promesse, le navigateur attend que la promesse se stabilise et renvoie la valeur obtenue.
Paramètres
-
Injection
Détails du script à injecter.
-
rappel
fonction facultative
Le paramètre
callback
se présente comme suit :(results: InjectionResult[]) => void
-
résultats
-
Renvoie
-
Promise<InjectionResult[]>
Chrome 90 et versions ultérieuresLes promesses sont compatibles avec Manifest V3 et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.
getRegisteredContentScripts()
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 pour l'extension.
-
rappel
fonction facultative
Le paramètre
callback
se présente comme suit :(scripts: RegisteredContentScript[]) => void
-
scripts
-
Renvoie
-
Promise<RegisteredContentScript[]>
Les promesses sont compatibles avec Manifest V3 et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.
insertCSS()
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 ayant échoué sont ignorées.
Paramètres
-
Injection
Détails des styles à insérer.
-
rappel
fonction facultative
Le paramètre
callback
se présente comme suit :() => void
Renvoie
-
Promise<void>
Chrome 90 et versions ultérieuresLes promesses sont compatibles avec Manifest V3 et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.
registerContentScripts()
chrome.scripting.registerContentScripts(
scripts: RegisteredContentScript[],
callback?: function,
)
Enregistre un ou plusieurs scripts de contenu pour cette extension.
Paramètres
-
scripts
Contient la liste des scripts à enregistrer. Si des erreurs se produisent lors de l'analyse des scripts ou de la validation du fichier, ou si les ID spécifiés existent déjà, aucun script n'est enregistré.
-
rappel
fonction facultative
Le paramètre
callback
se présente comme suit :() => void
Renvoie
-
Promise<void>
Les promesses sont compatibles avec Manifest V3 et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.
removeCSS()
chrome.scripting.removeCSS(
injection: CSSInjection,
callback?: function,
)
Supprime une feuille de style CSS précédemment insérée par cette extension d'un contexte cible.
Paramètres
-
Injection
Détails des styles à supprimer. Notez que les propriétés
css
,files
etorigin
doivent correspondre exactement à la feuille de style insérée viainsertCSS
. Toute tentative de suppression d'une feuille de style inexistante est noyée. -
rappel
fonction facultative
Le paramètre
callback
se présente comme suit :() => void
Renvoie
-
Promise<void>
Les promesses sont compatibles avec Manifest V3 et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.
unregisterContentScripts()
chrome.scripting.unregisterContentScripts(
filter?: ContentScriptFilter,
callback?: function,
)
Annule l'enregistrement des scripts de contenu pour cette extension.
Paramètres
-
filtre
ContentScriptFilter facultatif
Si ce paramètre est spécifié, seuls les scripts de contenu dynamique correspondant au filtre annulent l'enregistrement. Sinon, l'enregistrement de tous ses scripts de contenu dynamique est annulé.
-
rappel
fonction facultative
Le paramètre
callback
se présente comme suit :() => void
Renvoie
-
Promise<void>
Les promesses sont compatibles avec Manifest V3 et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.
updateContentScripts()
chrome.scripting.updateContentScripts(
scripts: RegisteredContentScript[],
callback?: function,
)
Met à jour un ou plusieurs scripts de contenu pour cette extension.
Paramètres
-
scripts
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 des scripts ou de la validation des fichiers, ou si les ID spécifiés ne correspondent pas à un script entièrement enregistré, aucun script n'est mis à jour.
-
rappel
fonction facultative
Le paramètre
callback
se présente comme suit :() => void
Renvoie
-
Promise<void>
Les promesses sont compatibles avec Manifest V3 et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.