chrome.userScripts

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" à votre fichier 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/*"
  ]
}

Disponibilité

Chrome 120 ou version ultérieure MV3 ou version ultérieure

Concepts et utilisation

Un script utilisateur est un extrait de code injecté dans une page Web pour modifier son apparence ou son comportement. Les scripts sont créés par les utilisateurs ou 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, le mode développeur est déjà activé 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.

  1. Accédez à la page "Extensions" en saisissant chrome://extensions dans un nouvel onglet. (De par leur conception, les URL chrome:// ne peuvent pas être associées à un lien.)

  2. Activez le mode développeur en cliquant sur le bouton d'activation situé à côté de Mode développeur.

    la page des extensions ;

    Page "Extensions" (chrome://extensions)

Vous pouvez déterminer si le mode développeur est activé en vérifiant 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 mondes isolés

Les scripts utilisateur et de contenu peuvent s'exécuter dans un monde isolé ou dans le monde principal. Un monde isolé est un environnement d'exécution qui n'est pas accessible à une page hôte ni à d'autres extensions. Cela permet à un script utilisateur de modifier son environnement JavaScript sans affecter la page hôte ni les scripts utilisateur et de contenu d'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 d'autres extensions. Les scripts exécutés dans le monde principal sont accessibles aux pages hôtes et aux autres extensions, et sont visibles par les pages hôtes et les 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 l'environnement USER_SCRIPT, appelez userScripts.configureWorld():

chrome.userScripts.configureWorld({
  csp: "script-src 'self'"
});

Messagerie

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 (ce qui signifie qu'ils peuvent appeler runtime.sendMessage() et runtime.connect() comme n'importe quelle autre partie d'une extension). Toutefois, ils sont reçus à l'aide de gestionnaires d'événements dédiés (c'est-à-dire qu'ils n'utilisent pas onMessage ou onConnect). Ces gestionnaires sont appelés runtime.onUserScriptMessage et runtime.onUserScriptConnect. Les gestionnaires dédiés permettent d'identifier plus facilement les messages provenant de 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 ajouter à nouveau en exécutant du code dans le gestionnaire d'événements runtime.onInstalled du service worker de l'extension. Ne répondez qu'à la raison "update" transmise au rappel d'événement.

Exemple

Cet exemple provient de l'exemple userScript de notre dépôt d'exemples.

Enregistrer un script

L'exemple suivant montre un appel de base à register(). Le premier argument est un tableau d'objets définissant les scripts à enregistrer. Il existe plus d'options que celles affichées ici.

chrome.userScripts.register([{
  id: 'test',
  matches: ['*://*/*'],
  js: [{code: 'alert("Hi!")'}]
}]);

Types

ExecutionWorld

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

Énumération


"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 qui est exempté du CSP de la page.

RegisteredUserScript

Propriétés

  • allFrames

    booléen facultatif

    Si la valeur est "true", l'injection se produit dans tous les frames, même si le frame n'est pas le frame le plus élevé de l'onglet. Les exigences concernant les URL sont vérifiées indépendamment pour chaque frame. Si les exigences ne sont pas respectées, le frame ne sera pas injecté dans les frames enfants. La valeur par défaut est "false", ce qui signifie que seul le frame supérieur est mis en correspondance.

  • excludeGlobs

    string[] facultatif

    Spécifie des modèles génériques pour les pages dans lesquelles ce script utilisateur NE sera PAS injecté.

  • excludeMatches

    string[] facultatif

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

  • id

    chaîne

    ID du script utilisateur spécifié dans l'appel d'API. Cette propriété ne doit pas commencer par un "_", car ce caractère est réservé en tant que préfixe pour les ID de script générés.

  • includeGlobs

    string[] facultatif

    Spécifie des modèles génériques pour les pages dans lesquelles ce script utilisateur sera injecté.

  • js

    ScriptSource[] facultatif

    Liste des objets ScriptSource définissant les sources de scripts à injecter dans les pages correspondantes. Cette propriété doit être spécifiée pour ${ref:register}. Lorsqu'elle est spécifiée, elle doit être un tableau non vide.

  • correspond à

    string[] facultatif

    Indique les pages dans lesquelles ce script utilisateur sera injecté. Pour en savoir plus sur la syntaxe de ces chaînes, consultez Formats de correspondance. Cette propriété doit être spécifiée pour ${ref:register}.

  • runAt

    RunAt facultatif

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

  • monde

    ExecutionWorld facultatif

    Environnement d'exécution JavaScript dans lequel exécuter le script. La valeur par défaut est `USER_SCRIPT`.

  • worldId

    chaîne facultatif

    En attente

    Si spécifié, spécifie un ID de monde de script utilisateur spécifique dans lequel exécuter. Valide uniquement si world est omis ou est USER_SCRIPT. Si cet attribut n'est pas spécifié, le script s'exécute dans l'environnement de script utilisateur par défaut. Les valeurs commençant par un trait de soulignement (_) sont réservées.

ScriptSource

Propriétés

  • code

    chaîne facultatif

    Chaîne contenant le code JavaScript à injecter. Vous devez spécifier un seul file ou code.

  • fichier

    chaîne facultatif

    Chemin du fichier JavaScript à injecter par rapport au répertoire racine de l'extension. Vous devez spécifier un seul file ou code.

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

  • csp

    chaîne facultatif

    Spécifie le csp mondial. La valeur par défaut est le csp mondial `ISOLATED`.

  • messagerie

    booléen facultatif

    Indique si les API de messagerie sont exposées. La valeur par défaut est false.

  • worldId

    chaîne facultatif

    En attente

    Spécifie l'ID du monde de script utilisateur spécifique à mettre à jour. Si elle n'est pas fournie, met à jour les propriétés de l'environnement du script utilisateur par défaut. Les valeurs commençant par un trait de soulignement (_) sont réservées.

Méthodes

configureWorld()

Promesse 
chrome.userScripts.configureWorld(
  properties: WorldProperties,
  callback?: function,
)

Configure l'environnement d'exécution `USER_SCRIPT`.

Paramètres

  • du bucket

    WorldProperties

    Contient la configuration du monde du script utilisateur.

  • rappel

    fonction facultatif

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

    () => void

Renvoie

  • Promise<void>

    Les promesses sont compatibles avec la version 3 du fichier manifeste 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 se résout avec le même type que celui transmis au rappel.

getScripts()

Promesse 
chrome.userScripts.getScripts(
  filter?: UserScriptFilter,
  callback?: function,
)

Renvoie tous les scripts utilisateur enregistrés dynamiquement pour cette extension.

Paramètres

  • filtre

    UserScriptFilter facultatif

    Si elle est spécifiée, cette méthode ne renvoie que les scripts utilisateur qui y correspondent.

  • rappel

    fonction facultatif

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

    (scripts: RegisteredUserScript[]) => void

Renvoie

  • Les promesses sont compatibles avec la version 3 du fichier manifeste 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 se résout avec le même type que celui transmis au rappel.

getWorldConfigurations()

Promesse en attente
chrome.userScripts.getWorldConfigurations(
  callback?: function,
)

Récupère toutes les configurations du monde enregistrées.

Paramètres

Renvoie

  • Promise<WorldProperties[]>

    Les promesses sont compatibles avec la version 3 du fichier manifeste 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 se résout avec le même type que celui transmis au rappel.

register()

Promesse 
chrome.userScripts.register(
  scripts: RegisteredUserScript[],
  callback?: function,
)

Inscrit un ou plusieurs scripts utilisateur pour cette extension.

Paramètres

  • Contient la liste des scripts utilisateur à enregistrer.

  • rappel

    fonction facultatif

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

    () => void

Renvoie

  • Promise<void>

    Les promesses sont compatibles avec la version 3 du fichier manifeste 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 se résout avec le même type que celui transmis au rappel.

resetWorldConfiguration()

Promesse en attente
chrome.userScripts.resetWorldConfiguration(
  worldId?: string,
  callback?: function,
)

Réinitialise la configuration d'un monde de script utilisateur. Tous les scripts qui injectent du contenu dans le monde avec l'ID spécifié utiliseront la configuration du monde par défaut.

Paramètres

  • worldId

    chaîne facultatif

    ID de l'univers du script utilisateur à réinitialiser. Si elle est omise, la configuration du monde par défaut est réinitialisée.

  • rappel

    fonction facultatif

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

    () => void

Renvoie

  • Promise<void>

    Les promesses sont compatibles avec la version 3 du fichier manifeste 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 se résout avec le même type que celui transmis au rappel.

unregister()

Promesse 
chrome.userScripts.unregister(
  filter?: UserScriptFilter,
  callback?: function,
)

Désinscrit tous les scripts utilisateur enregistrés dynamiquement pour cette extension.

Paramètres

  • filtre

    UserScriptFilter facultatif

    Si elle est spécifiée, cette méthode ne désinscrit que les scripts utilisateur qui lui correspondent.

  • rappel

    fonction facultatif

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

    () => void

Renvoie

  • Promise<void>

    Les promesses sont compatibles avec la version 3 du fichier manifeste 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 se résout avec le même type que celui transmis au rappel.

update()

Promesse 
chrome.userScripts.update(
  scripts: RegisteredUserScript[],
  callback?: function,
)

Met à jour un ou plusieurs scripts utilisateur pour cette extension.

Paramètres

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

    fonction facultatif

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

    () => void

Renvoie

  • Promise<void>

    Les promesses sont compatibles avec la version 3 du fichier manifeste 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 se résout avec le même type que celui transmis au rappel.