chrome.declarativeContent

Description

Autorisations

Concepts et utilisation

Declarative Content API 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 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().

Le PageStateMatcher établit une correspondance avec les pages Web si et seulement si tous les critères répertoriés sont remplis. Il peut correspondre à une URL de page, un sélecteur composé CSS ou l'état d'une page ajoutée 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 pour les sites Google comportant une vidéo, vous pouvez ajouter une deuxième condition, 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 une règle a au moins une condition remplie et exécute les actions. Les règles sont conservées 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'affiche aucun avertissement d'autorisation et, 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 la page

PageStateMatcher.pageurl correspond lorsque les critères d'URL sont remplis. Les critères les plus courants sont la concaténation de l'hôte, du chemin d'accès ou de l'URL, suivi de "Contient", "Est égal(e) à", "Préfixe" ou "Suffixe". Voici 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 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.

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 vos sélecteurs. Cela permet à Chrome de faire correspondre les sélecteurs plus efficacement.

Sélecteurs composés (OK)	Sélecteurs complexes (non acceptés)
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 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 d'état ajoutée aux favoris

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