chrome.declarativeContent

refresh date: 2026-09-25 robots: noindex

Beschrijving

Gebruik de chrome.declarativeContent API om acties uit te voeren op basis van de content van een pagina, zonder dat je rechten nodig hebt om de content van de pagina te lezen.

Rechten

declarativeContent

Gebruik

Met de Declarative Content API kun je de actie van je extensie aanzetten, afhankelijk van de URL van een webpagina of als een CSS-kiezer overeenkomt met een element op de pagina, zonder dat je hostrechten hoeft toe te voegen of een contentscript hoeft te injecteren.

Gebruik het recht activeTab om interactie met een pagina te hebben nadat de gebruiker op de actie van de extensie heeft geklikt.

Regels

Regels bestaan uit voorwaarden en acties. Als aan een van de voorwaarden wordt voldaan, worden alle acties uitgevoerd. De acties zijn setIcon en showAction.

De PageStateMatcher komt alleen overeen met webpagina's als aan alle vermelde criteria wordt voldaan. Deze kan overeenkomen met een pagina-URL, een samengestelde css-kiezer of de gebookmarkte status van een pagina. Met de volgende regel wordt de actie van de extensie op Google-pagina's aangezet als er een wachtwoordveld aanwezig is:

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

Als je de actie van de extensie ook wilt aanzetten voor Google-sites met een video, kun je een 2e voorwaarde toevoegen, omdat elke voorwaarde voldoende is om alle aangegeven acties te activeren:

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() ]
};

De gebeurtenis onPageChanged test of een regel ten minste één voldane voorwaarde heeft en voert de acties uit. Regels blijven behouden tijdens browsersessies. Daarom moet je tijdens de installatie van de extensie eerst removeRules gebruiken om eerder geïnstalleerde regels te wissen en daarna addRules gebruiken om nieuwe regels te registreren.

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

Met het recht activeTab toont je extensie geen rechtewaarschuwingen. Als de gebruiker op de extensieactie klikt, wordt deze alleen uitgevoerd op relevante pagina's.

Overeenkomende pagina-URL's

De PageStateMatcher.pageurl komt overeen als aan de URL-criteria is voldaan. De meest voorkomende criteria zijn een samenvoeging van host, pad of URL, gevolgd door Bevat, Is gelijk aan, Voorvoegsel of Achtervoegsel. De volgende tabel bevat een aantal voorbeelden:

Criteria Combinaties
{ hostSuffix: 'google.com' } Alle Google-URL's
{ pathPrefix: '/docs/extensions' } URL's van documentatie over extensies
{ urlContains: 'developer.chrome.com' } Alle URL's van documenten voor Chrome-ontwikkelaars

Alle criteria zijn hoofdlettergevoelig. Ga naar UrlFilter voor een volledige lijst met criteria.

CSS-overeenkomst

PageStateMatcher.css-voorwaarden moeten samengestelde selectors zijn. Dit betekent dat u geen combinators zoals witruimte of > in uw selectors kunt opnemen. Zo kan Chrome de kiezers efficiënter matchen.

Samengestelde kiezers (OK) Complexe kiezers (niet OK)
a div p
iframe.special[src^='http'] p>span.highlight
ns|* p + ol
#abcd:checked p::first-line

CSS-voorwaarden komen alleen overeen met weergegeven elementen: als een element dat overeenkomt met uw kiezer display:none is of een van de bovenliggende elementen display:none is, komt de voorwaarde niet overeen. Elementen die zijn opgemaakt met visibility:hidden, buiten het scherm zijn geplaatst of verborgen zijn door andere elementen, kunnen nog steeds overeenkomen met uw voorwaarde.

Overeenkomst met gebookmarkte status

Met de voorwaarde PageStateMatcher.isBookmarked kun je de status van de huidige URL in het profiel van de gebruiker matchen. Als je deze voorwaarde wilt gebruiken, moet het recht bookmarks worden gedefinieerd in het manifest van de extensie.

Typen

Type

ImageData

PageStateMatcher

Komt overeen met de status van een webpagina op basis van verschillende criteria.

Eigenschappen

  • constructor

    ongeldig

    De functie constructor ziet er zo uit: 

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

  • css

    string[] optioneel

    Komt overeen als alle css-kiezers in de matrix overeenkomen met weergegeven elementen in een frame met dezelfde oorsprong als het hoofdframe van de pagina. Alle selectors in deze matrix moeten samengestelde selectors zijn om de overeenkomst te versnellen. Opmerking: Als u honderden css-kiezers vermeldt of css-kiezers vermeldt die honderden keren per pagina overeenkomen, kan dit websites vertragen.

  • isBookmarked

    booleaans optioneel

    Chrome 45+

    Komt overeen als de bladwijzerstatus van de pagina gelijk is aan de opgegeven waarde. Hiervoor is het recht Bookmarks vereist.

  • pageUrl

    UrlFilter optioneel

    Komt overeen als aan de voorwaarden van de UrlFilter wordt voldaan voor de URL op het hoogste niveau van de pagina.

RequestContentScript

Declaratieve gebeurtenisactie die een contentscript injecteert.

WAARSCHUWING: Deze actie is nog experimenteel en wordt niet ondersteund in stabiele builds van Chrome.

Eigenschappen

  • constructor

    ongeldig

    De functie constructor ziet er zo uit: 

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

  • allFrames

    booleaans optioneel

    Of het contentscript wordt uitgevoerd in alle frames van de overeenkomende pagina of alleen in het bovenste frame. De standaardwaarde is false.

  • css

    string[] optioneel

    Namen van css-bestanden die moeten worden geïnjecteerd als onderdeel van het contentscript.

  • js

    string[] optioneel

    Namen van JavaScript-bestanden die moeten worden geïnjecteerd als onderdeel van het contentscript.

  • matchAboutBlank

    booleaans optioneel

    Of het contentscript moet worden ingevoegd op about:blank en about:srcdoc. De standaardwaarde is false.

SetIcon

Declaratieve gebeurtenisactie die het n-dip vierkante icoon instelt voor de pagina-actie of browseractie van de extensie terwijl aan de bijbehorende voorwaarden wordt voldaan. Deze actie kan worden gebruikt zonder hostrechten, maar de extensie moet een pagina- of browseractie hebben.

Er moet precies één imageData of path worden ingevoerd. Beide zijn woordenboeken die een aantal pixels toewijzen aan een afbeeldingsweergave. De afbeeldingsweergave in imageData is een ImageData-object, bijvoorbeeld van een canvas-element, terwijl de afbeeldingsweergave in path het pad naar een afbeeldingsbestand is ten opzichte van het manifest van de extensie. Als er scale schermpixels in een apparaatonafhankelijke pixel passen, wordt het icoon scale * n gebruikt. Als die schaal ontbreekt, wordt het formaat van een andere afbeelding aangepast aan het vereiste formaat.

Eigenschappen

  • constructor

    ongeldig

    De functie constructor ziet er zo uit: 

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

  • imageData

    ImageData | object optioneel

    Een ImageData-object of een woordenboek {size -> ImageData} dat een icoon vertegenwoordigt dat moet worden ingesteld. Als het icoon is gespecificeerd als een woordenboek, wordt de gebruikte afbeelding gekozen op basis van de pixeldichtheid van het scherm. Als het aantal afbeeldingspixels dat in één schermruimte-eenheid past gelijk is aan scale, wordt een afbeelding met de grootte scale * n geselecteerd, waarbij n de grootte van het icoon in de UI is. Er moet minstens één afbeelding worden ingevoerd. details.imageData = foo is gelijk aan details.imageData = {'16': foo}.

ShowAction

Chrome 97+

Een declaratieve gebeurtenisactie die de actie van de werkbalk van de extensie instelt op een aangezette status terwijl aan de bijbehorende voorwaarden wordt voldaan. Deze actie kan worden gebruikt zonder hostrechten. Als de extensie het recht activeTab heeft, wordt door op de pagina-actie te klikken toegang verleend tot het actieve tabblad.

Op pagina's waar niet aan de voorwaarden wordt voldaan, wordt de werkbalkactie van de extensie in grijstinten weergegeven. Als je erop klikt, wordt het contextmenu geopend in plaats van dat de actie wordt geactiveerd.

Eigenschappen

ShowPageAction

Beëindigd sinds Chrome 97

Gebruik declarativeContent.ShowAction.

Een declaratieve gebeurtenisactie die de pagina-actie van de extensie instelt op een aangezette status terwijl aan de bijbehorende voorwaarden wordt voldaan. Deze actie kan worden gebruikt zonder hostrechten, maar de extensie moet een pagina-actie hebben. Als de extensie het recht activeTab heeft, wordt door op de pagina-actie te klikken toegang verleend tot het actieve tabblad.

Op pagina's waar niet aan de voorwaarden wordt voldaan, wordt de werkbalkactie van de extensie in grijstinten weergegeven. Als je erop klikt, wordt het contextmenu geopend in plaats van dat de actie wordt geactiveerd.

Eigenschappen

Evenementen

onPageChanged

Biedt de Declarative Event API die bestaat uit addRules, removeRules en getRules.

Voorwaarden

PageStateMatcher

Acties

RequestContentScript

SetIcon

ShowPageAction

ShowAction