chrome.declarativeContent

Description

Autorisations

Concepts et utilisation

L'API Content Declarative 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 hôte ni à injecter un script de contenu.

Utilisez l'autorisation activeTab pour interagir avec une page après 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().

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 composé CSS ou à l'état "Ajouté aux favoris" d'une page. 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 pour les sites Google contenant une vidéo, vous pouvez ajouter une deuxième condition, car chaque condition est suffisante pour 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 vérifie si une règle comporte au moins une condition remplie et exécute les actions. Les règles persistent entre les sessions de navigation. 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 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 aucune alerte d'autorisation. Lorsque l'utilisateur clique sur l'action de l'extension, elle ne s'exécute que sur les pages pertinentes.

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 concatenaison d'hôte, de chemin ou d'URL, suivie de "Contient", "Est é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 des pages de documentation des 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 CSS

Les conditions PageStateMatcher.css doivent être des sélecteurs composés. Autrement dit, 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 conformes)
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 en dehors de l'écran ou masqués par d'autres éléments peuvent toujours faire correspondre votre condition.

Correspondance de l'état "Ajouté aux favoris"

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