chrome.declarativeContent

refresh date: 2026-09-25 robots: noindex

Description

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

Autorisations

declarativeContent

Utilisation

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

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

Règles

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

Le PageStateMatcher correspond aux pages Web si et seulement si tous les critères listés sont remplis. Il peut correspondre à une URL de page, à un sélecteur CSS composé ou à l'état de mise en favoris d'une page. La règle suivante permet à l'extension d'effectuer une action 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 pour les sites Google avec une vidéo, vous pouvez ajouter une deuxième condition, car chaque condition suffit à déclencher toutes les 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 une règle comporte au moins une condition remplie et exécute les actions. Les règles persistent d'une session de navigation à l'autre. Par conséquent, lors de l'installation de l'extension, vous devez d'abord utiliser removeRules pour effacer les règles précédemment installées, puis utiliser 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'affichera aucun avertissement d'autorisation. Lorsque l'utilisateur cliquera sur l'action de l'extension, celle-ci ne s'exécutera que sur les pages concernées.

Mise en correspondance des URL de page

PageStateMatcher.pageurl correspond lorsque les critères d'URL sont remplis. Les critères les plus courants sont une concaténation de l'hôte, du chemin d'accès ou de l'URL, suivie de "Contient", "Égal à", "Préfixe" ou "Suffixe". Vous trouverez quelques exemples dans le tableau suivant :

Critères Correspond à
{ hostSuffix: 'google.com' } Toutes les URL Google
{ pathPrefix: '/docs/extensions' } URL de la documentation sur les extensions
{ urlContains: 'developer.chrome.com' } Toutes les URL de la documentation pour les 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 des CSS

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

Sélecteurs composés (OK) Sélecteurs complexes (non OK)
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 correspondant à votre sélecteur est display:none ou si l'un de ses éléments parents est display:none, la condition ne correspond pas. Les éléments stylisés avec visibility:hidden, positionnés hors écran ou masqués par d'autres éléments peuvent toujours correspondre à votre condition.

Mise en correspondance de l'état "Ajouté aux favoris"

La condition PageStateMatcher.isBookmarked permet de faire correspondre l'état de mise en favoris de l'URL actuelle dans le profil de l'utilisateur. Pour utiliser cette condition, l'autorisation "bookmarks" doit être déclarée dans le manifeste de l'extension.

Types

Type

ImageData

PageStateMatcher

Correspond à 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

    La condition est remplie si tous les sélecteurs CSS du tableau correspondent aux éléments affichés dans un frame ayant la même origine que le frame 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 : L'utilisation de centaines de sélecteurs CSS ou de sélecteurs CSS qui correspondent à des centaines d'éléments par page peut ralentir les sites Web.

  • isBookmarked

    booléen facultatif

    Chrome 45 et versions ultérieures

    Établit une correspondance si l'état de la page (ajoutée ou non aux favoris) est égal à la valeur spécifiée. Nécessite l'autorisation "bookmarks".

  • 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éclaratif qui injecte un script de contenu.

AVERTISSEMENT : Cette action est encore expérimentale et n'est pas compatible avec 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 s'il faut insérer le script de contenu 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 de page ou l'action de 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 disposer d'une action de page ou de navigateur.

Vous devez spécifier soit imageData, soit path. Les deux sont des dictionnaires qui mappent un 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 est le chemin d'accès à un fichier image par rapport au fichier manifeste de l'extension. Si scale pixels d'écran 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

    Objet ImageData ou 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é de pixels de l'écran. Si le nombre de pixels d'image qui tiennent dans une unité d'espace d'écran est égal à scale, une image de taille scale * n est sélectionnée, où n correspond à 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 et versions ultérieures

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'organisateur. Si l'extension dispose de l'autorisation activeTab, le fait de cliquer sur l'action de page lui accorde l'accès à l'onglet actif.

Sur les pages où les conditions ne sont pas remplies, l'action de la barre d'outils de l'extension sera en niveaux de gris. En cliquant dessus, le menu contextuel s'ouvrira au lieu de déclencher l'action.

Propriétés

ShowPageAction

Obsolète depuis Chrome 97

Veuillez utiliser declarativeContent.ShowAction.

Action d'événement déclarative qui définit l'action de 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 disposer d'une action de page. Si l'extension dispose de l'autorisation activeTab, le fait de cliquer sur l'action de page lui accorde l'accès à l'onglet actif.

Sur les pages où les conditions ne sont pas remplies, l'action de la barre d'outils de l'extension sera en niveaux de gris. En cliquant dessus, le menu contextuel s'ouvrira au lieu de déclencher l'action.

Propriétés

Événements

onPageChanged

Fournit l'API Declarative Event, qui se compose de addRules, removeRules et getRules.

Conditions

PageStateMatcher

Actions

RequestContentScript

SetIcon

ShowPageAction

ShowAction