Description
Utilisez l'API userScripts
pour exécuter des scripts utilisateur dans le contexte des scripts utilisateur.
Autorisations
userScripts
Pour utiliser l'API chrome.userScripts
, ajoutez l'autorisation "userScripts"
à vos fichiers manifest.json et "host_permissions"
pour les sites sur lesquels vous souhaitez exécuter des scripts.
{
"name": "User script test extension",
"manifest_version": 3,
"minimum_chrome_version": "120",
"permissions": [
"userScripts"
],
"host_permissions": [
"*://example.com/*"
]
}
Garantie de disponibilité
Concepts et utilisation
Un script utilisateur est un extrait de code injecté dans une page Web pour en modifier l'apparence ou le comportement. Les scripts sont soit créés par des utilisateurs, soit téléchargés à partir d'un dépôt de scripts ou d'une extension de script utilisateur.
Mode développeur pour les utilisateurs d'extensions
En tant que développeur d'extensions, vous avez déjà activé le mode développeur dans votre installation de Chrome. Pour les extensions de script utilisateur, vos utilisateurs devront également activer le mode développeur. Voici des instructions que vous pouvez copier et coller dans votre propre documentation.
- Accédez à la page "Extensions" en saisissant
chrome://extensions
dans un nouvel onglet. Par nature, les URLchrome://
ne peuvent pas contenir de liens. Activez le mode développeur en cliquant sur le bouton bascule à côté de Mode développeur.
Pour déterminer si le mode développeur est activé, vérifiez si chrome.userScripts
génère une erreur. Exemple :
function isUserScriptsAvailable() {
try {
// Property access which throws if developer mode is not enabled.
chrome.userScripts;
return true;
} catch {
// Not available.
return false;
}
}
Travailler dans des environnements isolés
Les scripts d'utilisateur et de contenu peuvent s'exécuter dans un environnement isolé ou dans l'environnement principal. Un monde isolé est un environnement d'exécution auquel une page hôte ou d'autres extensions ne peuvent pas accéder. Cela permet à un script utilisateur de modifier son environnement JavaScript sans affecter la page hôte ni les scripts utilisateur et de contenu des autres extensions. À l'inverse, les scripts utilisateur (et les scripts de contenu) ne sont pas visibles par la page hôte ni par les scripts utilisateur et de contenu des autres extensions. Les scripts exécutés dans le monde principal sont accessibles aux pages hôtes et à d'autres extensions, et sont visibles par les pages hôtes et par d'autres extensions. Pour sélectionner le monde, transmettez "USER_SCRIPT"
ou "MAIN"
lorsque vous appelez userScripts.register()
.
Pour configurer une règle de sécurité du contenu pour le monde USER_SCRIPT
, appelez userScripts.configureWorld()
:
chrome.userScripts.configureWorld({
csp: "script-src 'self'"
});
Messagerie
Tout comme les scripts de contenu et les documents hors écran, les scripts utilisateur communiquent avec d'autres parties d'une extension à l'aide de la messagerie (ils peuvent appeler runtime.sendMessage()
et runtime.connect()
comme le ferait n'importe quelle autre partie d'une extension). Cependant, ils sont reçus à l'aide de gestionnaires d'événements dédiés (qui n'utilisent pas onMessage
ni onConnect
). Ces gestionnaires sont appelés runtime.onUserScriptMessage
et runtime.onUserScriptConnect
. Les gestionnaires dédiés facilitent l'identification des messages dans les scripts utilisateur, qui constituent un contexte moins fiable.
Avant d'envoyer un message, vous devez appeler configureWorld()
avec l'argument messaging
défini sur true
. Notez que les arguments csp
et messaging
peuvent être transmis en même temps.
chrome.userScripts.configureWorld({
messaging: true
});
Mises à jour des extensions
Les scripts utilisateur sont effacés lorsqu'une extension est mise à jour. Vous pouvez les rajouter en exécutant du code dans le gestionnaire d'événements runtime.onInstalled
du service worker de l'extension. Répondez uniquement au motif "update"
transmis au rappel de l'événement.
Exemple
Cet exemple provient de l'exemple userScript de notre dépôt d'exemples.
Enregistrer un script
L'exemple suivant illustre un appel de base à register()
. Le premier argument est un tableau d'objets définissant les scripts à enregistrer. Il y a plus d'options que celles présentées ici.
chrome.userScripts.register([{
id: 'test',
matches: ['*://*/*'],
js: [{code: 'alert("Hi!")'}]
}]);
Types
ExecutionWorld
Monde JavaScript dans lequel un script utilisateur doit s'exécuter.
Enum
"MAIN"
Spécifie l'environnement d'exécution du DOM, qui est l'environnement d'exécution partagé avec le code JavaScript de la page hôte.
"USER_SCRIPT"
Spécifie l'environnement d'exécution spécifique aux scripts utilisateur et exempt de la CSP de la page.
RegisteredUserScript
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 sont pas ceux situés tout en haut 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.
-
excludeGlobs
string[] facultatif
Spécifie les formats de caractères génériques pour les pages dans lesquelles ce script utilisateur ne sera PAS injecté.
-
excludeMatches
string[] facultatif
Exclut les pages dans lesquelles ce script utilisateur serait autrement injecté. Consultez Formats de correspondance pour en savoir plus sur la syntaxe de ces chaînes.
-
id
chaîne
ID du script utilisateur spécifié dans l'appel d'API. Cette propriété ne doit pas commencer par "_", car elle est réservée en tant que préfixe pour les ID de script générés.
-
includeGlobs
string[] facultatif
Spécifie les formats de caractères génériques pour les pages dans lesquelles ce script utilisateur sera injecté.
-
js
Liste des objets ScriptSource définissant les sources des scripts à injecter dans les pages correspondantes.
-
correspondances
string[] facultatif
Spécifie les pages dans lesquelles ce script utilisateur sera injecté. Consultez Formats de correspondance pour en savoir plus sur la syntaxe de ces chaînes. Cette propriété doit être spécifiée pour ${ref:register}.
-
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
Environnement d'exécution JavaScript dans lequel exécuter le script. La valeur par défaut est
`USER_SCRIPT`
.
ScriptSource
Propriétés
-
code
string facultatif
Chaîne contenant le code JavaScript à injecter. Vous ne devez spécifier qu'une seule des options
file
oucode
. -
fichier
string facultatif
Chemin du fichier JavaScript à injecter par rapport au répertoire racine de l'extension. Vous ne devez spécifier qu'une seule des options
file
oucode
.
UserScriptFilter
Propriétés
-
ids
string[] facultatif
getScripts
ne renvoie que les scripts dont les ID sont spécifiés dans cette liste.
WorldProperties
Propriétés
-
CSS
string facultatif
Spécifie le CSS "World". La valeur par défaut est le CSS
`ISOLATED`
global. -
messagerie : option Messages [Google My Business]
Booléen facultatif
Indique si les API de messagerie sont exposées. La valeur par défaut est
false
.
Méthodes
configureWorld()
chrome.userScripts.configureWorld(
properties: WorldProperties,
callback?: function,
)
Configure l'environnement d'exécution `USER_SCRIPT`
.
Paramètres
-
du bucket
Contient la configuration globale du script utilisateur.
-
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.
getScripts()
chrome.userScripts.getScripts(
filter?: UserScriptFilter,
callback?: function,
)
Renvoie tous les scripts utilisateur enregistrés dynamiquement pour cette extension.
Paramètres
-
filtre
UserScriptFilter facultatif
Si cette méthode est spécifiée, elle ne renvoie que les scripts utilisateur qui lui correspondent.
-
rappel
fonction facultative
Le paramètre
callback
se présente comme suit :(scripts: RegisteredUserScript[]) => void
-
scripts
-
Renvoie
-
Promise<RegisteredUserScript[]>
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.
register()
chrome.userScripts.register(
scripts: RegisteredUserScript[],
callback?: function,
)
Enregistre un ou plusieurs scripts utilisateur pour cette extension.
Paramètres
-
scripts
Contient la liste des scripts utilisateur à enregistrer.
-
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.
unregister()
chrome.userScripts.unregister(
filter?: UserScriptFilter,
callback?: function,
)
Annule l'enregistrement de tous les scripts utilisateur enregistrés dynamiquement pour cette extension.
Paramètres
-
filtre
UserScriptFilter facultatif
Si elle est spécifiée, cette méthode annule l'enregistrement uniquement des scripts utilisateur qui lui correspondent.
-
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.
update()
chrome.userScripts.update(
scripts: RegisteredUserScript[],
callback?: function,
)
Met à jour un ou plusieurs scripts utilisateur pour cette extension.
Paramètres
-
scripts
Contient la liste des scripts utilisateur à 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.