chrome.declarativeContent

Description

Utilisez l'API chrome.declarativeContent pour effectuer des actions en fonction du contenu d'une page, sans avoir besoin d'autorisation pour en lire le contenu.

Autorisations

declarativeContent

Concepts et utilisation

L'API Declarative Content API vous permet d'activer l'action de votre extension en fonction de l'URL d'une ou si un sélecteur CSS correspond à un élément de la page, sans qu'il soit nécessaire ajouter des autorisations d'hôte ou injecter un script de contenu.

Utilisez l'autorisation activeTab pour interagir avec une page une fois que l'utilisateur a cliqué sur l' l'action de l'extension.

Règles

Les règles sont constituées de conditions et d'actions. Si l'une des conditions est remplie, toutes les actions sont exécuté. Les actions sont setIcon() et showAction().

Le PageStateMatcher établit une correspondance avec les pages Web si et seulement si toutes les pages sont listées si certains critères sont remplis. Il peut correspondre à l'URL d'une page, à un sélecteur composé CSS ou l'ajout d'une page aux favoris. La règle suivante active l'action de l'extension sur les pages Google lorsqu'un champ de mot de passe est présent:

let rule1 = {
  conditions: [
    new chrome.declarativeContent.PageStateMatcher({
      pageUrl: { hostSuffix: '.google.com', schemes: ['https'] },
      css: ["input[type='password']"]
    })
  ],
  actions: [ new chrome.declarativeContent.ShowAction() ]
};

Pour activer également l'action de l'extension sur les sites Google associés à une vidéo, vous pouvez ajouter une seconde , car chaque condition est suffisante pour déclencher l'ensemble des actions spécifiées:

let rule2 = {
  conditions: [
    new chrome.declarativeContent.PageStateMatcher({
      pageUrl: { hostSuffix: '.google.com', schemes: ['https'] },
      css: ["input[type='password']"]
    }),
    new chrome.declarativeContent.PageStateMatcher({
      css: ["video"]
    })
  ],
  actions: [ new chrome.declarativeContent.ShowAction() ]
};

L'événement onPageChanged teste si au moins une règle a été exécutée condition et exécute les actions. Les règles sont conservées d'une session de navigation à l'autre. Par conséquent, pendant temps d'installation de l'extension, vous devez d'abord utiliser removeRules pour effacer des règles précédemment installées, puis utilisez addRules pour en enregistrer de nouvelles.

chrome.runtime.onInstalled.addListener(function(details) {
  chrome.declarativeContent.onPageChanged.removeRules(undefined, function() {
    chrome.declarativeContent.onPageChanged.addRules([rule2]);
  });
});

Avec l'autorisation activeTab, votre extension n'affiche aucune autorisation d'avertissement. De plus, lorsque l'utilisateur clique sur l'action de l'extension, celle-ci ne s'exécute que sur les pages pertinentes.

Mise en correspondance des URL de pages

Le PageStateMatcher.pageurl correspond lorsque les critères d'URL sont remplis. La les critères les plus courants sont la concaténation de l'hôte, du chemin d'accès ou de l'URL, suivie de "Contient", "Est égal(e) à", "Préfixe" ou Suffixe. Le tableau suivant contient quelques exemples:

Critères Correspond à
{ hostSuffix: 'google.com' } Toutes les URL Google
{ pathPrefix: '/docs/extensions' } URL des documents d'extension
{ urlContains: 'developer.chrome.com' } Toutes les URL de documentation des développeurs Chrome

Tous les critères sont sensibles à la casse. Pour obtenir la liste complète des critères, consultez UrlFilter.

Mise en correspondance CSS

Les conditions PageStateMatcher.css doivent être des sélecteurs composés, Cela signifie que vous ne pouvez pas inclure de combinateurs tels que des espaces blancs ou ">". dans votre sélecteurs. Cela permet à Chrome de faire correspondre les sélecteurs plus efficacement.

Sélecteurs composés (OK) Sélecteurs complexes (non autorisé)
a div p
iframe.special[src^='http'] p>span.highlight
ns|* p + ol
#abcd:checked p::first-line

Les conditions CSS ne correspondent qu'aux éléments affichés: si un élément qui correspond à votre sélecteur est display:none ou l'un de ses éléments parents est display:none, cela n'entraîne pas la modification de la condition correspond. Éléments stylisés avec visibility:hidden, positionnés en dehors de l'écran ou masqués par d'autres éléments peut toujours faire correspondre votre condition.

Correspondance des états ajoutés aux favoris

La condition PageStateMatcher.isBookmarked permet la mise en correspondance des l'état de l'URL actuelle dans les favoris du profil de l'utilisateur. Pour utiliser cette condition, "favoris" l'autorisation doit être déclarée dans le fichier manifeste de l'extension.

Types

Type

ImageData

PageStateMatcher

Établit une correspondance avec l'état d'une page Web en fonction de différents critères.

Propriétés

  • constructor

    vide

    La fonction constructor se présente comme suit: 

    (arg: PageStateMatcher) => {...}

  • css

    string[] facultatif

    Renvoie une correspondance si tous les sélecteurs CSS du tableau correspondent aux éléments affichés dans un cadre ayant la même origine que le cadre principal de la page. Tous les sélecteurs de ce tableau doivent être des sélecteurs composés pour accélérer la mise en correspondance. Remarque: Répertorier des centaines de sélecteurs CSS ou des sélecteurs CSS qui correspondent des centaines de fois par page peut ralentir les sites Web.

  • isBookmarked

    Booléen facultatif

    Chrome 45 ou version ultérieure

    Trouve une correspondance si la page a été ajoutée aux favoris et correspond à la valeur spécifiée. Nécessite l'autorisation d'ajouter aux favoris.

  • pageUrl

    UrlFilter facultatif

    Correspond si les conditions de UrlFilter sont remplies pour l'URL de premier niveau de la page.

RequestContentScript

Action d'événement déclarative qui injecte un script de contenu.

AVERTISSEMENT:Cette action est encore au stade expérimental et n'est pas prise en charge dans les versions stables de Chrome.

Propriétés

  • constructor

    vide

    La fonction constructor se présente comme suit: 

    (arg: RequestContentScript) => {...}

  • allFrames

    Booléen facultatif

    Indique si le script de contenu s'exécute dans tous les cadres de la page correspondante ou uniquement dans le cadre supérieur. La valeur par défaut est false.

  • css

    string[] facultatif

    Noms des fichiers CSS à injecter dans le script de contenu.

  • js

    string[] facultatif

    Noms des fichiers JavaScript à injecter dans le script de contenu.

  • matchAboutBlank

    Booléen facultatif

    Indique si le script de contenu doit être inséré sur about:blank et about:srcdoc. La valeur par défaut est false.

SetIcon

Action d'événement déclarative qui définit l'icône carrée n-dip pour l'action sur la page ou l'action dans le navigateur de l'extension lorsque les conditions correspondantes sont remplies. Cette action peut être utilisée sans autorisations d'hôte, mais l'extension doit avoir une action de page ou de navigateur.

Vous ne devez spécifier qu'une seule propriété imageData ou path. Les deux sont des dictionnaires mappant un certain nombre de pixels à une représentation d'image. La représentation de l'image dans imageData est un objet ImageData. (par exemple, à partir d'un élément canvas), tandis que la représentation de l'image dans path correspond au chemin d'accès à un fichier image relatif au fichier manifeste de l'extension. Si des pixels d'écran scale tiennent dans un pixel indépendant de l'appareil, l'icône scale * n est utilisée. Si cette échelle est manquante, une autre image est redimensionnée à la taille requise.

Propriétés

  • constructor

    vide

    La fonction constructor se présente comme suit: 

    (arg: SetIcon) => {...}

  • imageData

    ImageData | objet facultatif

    Un objet ImageData ou un dictionnaire {size -> ImageData} représentant une icône à définir. Si l'icône est spécifiée sous forme de dictionnaire, l'image utilisée est choisie en fonction de la densité en pixels de l'écran. Si le nombre de pixels d'image pouvant tenir dans une unité d'espace à l'écran est égal à scale, une image de taille scale * n est sélectionnée, où n est la taille de l'icône dans l'UI. Vous devez spécifier au moins une image. Notez que details.imageData = foo équivaut à details.imageData = {'16': foo}.

ShowAction

Chrome 97 ou version ultérieure

Action d'événement déclarative qui définit l'action de la barre d'outils de l'extension sur un état activé lorsque les conditions correspondantes sont remplies. Cette action peut être utilisée sans autorisations d'hôte. Si l'extension dispose de l'autorisation activeTab, le fait de cliquer sur l'action de la page permet d'accéder à l'onglet actif.

Sur les pages où les conditions ne sont pas remplies, l'action de la barre d'outils de l'extension apparaît en niveaux de gris. Cliquez dessus pour ouvrir le menu contextuel, au lieu de déclencher l'action.

Propriétés

ShowPageAction

<ph type="x-smartling-placeholder"></ph> Obsolète depuis Chrome 97

Veuillez utiliser declarativeContent.ShowAction.

Action d'événement déclarative qui définit l'action sur la page de l'extension sur un état activé lorsque les conditions correspondantes sont remplies. Cette action peut être utilisée sans autorisations d'hôte, mais l'extension doit avoir une action de page. Si l'extension dispose de l'autorisation activeTab, le fait de cliquer sur l'action de la page permet d'accéder à l'onglet actif.

Sur les pages où les conditions ne sont pas remplies, l'action de la barre d'outils de l'extension apparaît en niveaux de gris. Cliquez dessus pour ouvrir le menu contextuel, au lieu de déclencher l'action.

Propriétés

Événements

onPageChanged

Fournit l'API Declarative Event composée de addRules, removeRules et getRules.

Conditions

PageStateMatcher

Actions

RequestContentScript

SetIcon

ShowPageAction

ShowAction