Description
Utilisez l'API chrome.declarativeContent
pour effectuer des actions en fonction du contenu d'une page, sans avoir besoin d'être autorisé à en lire le contenu.
Autorisations
declarativeContent
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.
Types
ImageDataType
Consultez la page https://developer.mozilla.org/en-US/docs/Web/API/ImageData.
Type
ImageData
PageStateMatcher
Correspond à l'état d'une page Web en fonction de différents critères.
Propriétés
-
constructor
void
La fonction
constructor
se présente comme suit :(arg: PageStateMatcher) => {...}
-
arg
-
retours
-
-
css
string[] facultatif
Recherche 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 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: Le référencement de centaines de sélecteurs CSS ou de sélecteurs CSS correspondant à des centaines de fois par page peut ralentir les sites Web.
-
isBookmarked
Booléen facultatif
Chrome 45 ou version ultérieureRecherche une correspondance si l'état de la page ajouté aux favoris est égal à la valeur spécifiée. Nécessite l'autorisation d'ajout aux favoris.
-
pageUrl
UrlFilter facultatif
Recherche une correspondance 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 expérimentale et n'est pas compatible avec les versions stables de Chrome.
Propriétés
-
constructor
void
La fonction
constructor
se présente comme suit :(arg: RequestContentScript) => {...}
-
retours
-
-
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é dans
about:blank
etabout:srcdoc
. La valeur par défaut estfalse
.
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 du 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 des options imageData
ou path
. Ces deux dictionnaires sont des dictionnaires mappant un certain nombre de pixels à une représentation d'image. La représentation d'image dans imageData
est un objet ImageData, par exemple à partir d'un élément canvas
, tandis que la représentation d'image dans path
est le chemin d'accès à un fichier image par rapport au fichier manifeste de l'extension. Si scale
pixels de l'écran rentrent 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
void
La fonction
constructor
se présente comme suit :(arg: SetIcon) => {...}
-
arg
-
retours
-
-
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é en pixels de l'écran. Si le nombre de pixels de l'image qui tiennent dans une unité d'espace à l'écran est égal àscale
, une image de taillescale * n
est sélectionnée, où n correspond à la taille de l'icône dans l'interface utilisateur. Vous devez spécifier au moins une image. Notez quedetails.imageData = foo
équivaut àdetails.imageData = {'16': foo}
.
ShowAction
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 sur la page permet d'accéder à l'onglet actif.
Sur les pages où les conditions ne sont pas remplies, l'action de l'extension dans la barre d'outils s'affiche en nuances de gris. Lorsque vous cliquez dessus, le menu contextuel s'ouvre au lieu de déclencher l'action.
Propriétés
-
constructor
void
La fonction
constructor
se présente comme suit :(arg: ShowAction) => {...}
-
arg
-
retours
-
ShowPageAction
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 autorisation 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 sur la page permet d'accéder à l'onglet actif.
Sur les pages où les conditions ne sont pas remplies, l'action de l'extension dans la barre d'outils s'affiche en nuances de gris. Lorsque vous cliquez dessus, le menu contextuel s'ouvre au lieu de déclencher l'action.
Propriétés
-
constructor
void
La fonction
constructor
se présente comme suit :(arg: ShowPageAction) => {...}
-
arg
-
retours
-
Événements
onPageChanged
Fournit l'API Declarative Event composée de addRules
, removeRules
et getRules
.