browser.declarativeContent

Beschrijving

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

Rechten

declarativeContent

Concepten en 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-selector overeenkomt met een element op de pagina, zonder dat je hostrechten hoeft toe te voegen of een content script hoeft te injecteren.

Gebruik het recht activeTab om interactie te hebben met een pagina 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. Het kan overeenkomen met een pagina-URL, een samengestelde css-kiezer of de status van een pagina als bookmark. 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 browser.declarativeContent.PageStateMatcher({
      pageUrl: { hostSuffix: '.google.com', schemes: ['https'] },
      css: ["input[type='password']"]
    })
  ],
  actions: [ new browser.declarativeContent.ShowAction() ]
};

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

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

De gebeurtenis onPageChanged test of een regel ten minste één vervulde 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 om nieuwe regels te registreren.

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

Met het recht activeTab toont je extensie geen waarschuwingen voor rechten en wordt de extensie alleen uitgevoerd op relevante pagina's als de gebruiker op de extensieactie klikt.

Overeenkomsten met pagina-URL's

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

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

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

CSS-overeenkomsten

PageStateMatcher.css-voorwaarden moeten samengestelde selectoren zijn. Dit betekent dat u geen combinatoren zoals witruimte of > in uw selectoren 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 getoonde 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 met de stijl visibility:hidden, die buiten het scherm zijn geplaatst of verborgen zijn door andere elementen, kunnen er nog steeds voor zorgen dat je aan de voorwaarde voldoet.

Overeenkomende bookmarkstatus

Met de voorwaarde PageStateMatcher.isBookmarked kan de status van de huidige URL in het gebruikersprofiel worden vergeleken met de status van de URL in de bladwijzers. Als je deze voorwaarde wilt gebruiken, moet je het recht 'bookmarks' definiëren in het manifest van de extensie.

Typen

Type

ImageData

PageStateMatcher

Vergelijkt de status van een webpagina op basis van verschillende criteria.

Eigenschappen

  • constructeur

    nietig

    De functie constructor ziet er zo uit: 

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

  • css

    string[] optioneel

    Komt overeen als alle css-kiezers in de array overeenkomen met getoonde elementen in een frame met dezelfde oorsprong als het hoofdframe van de pagina. Alle selectors in deze array moeten samengestelde selectors zijn om de matching 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 status van de pagina in de bladwijzers gelijk is aan de aangegeven waarde. Hiervoor is het bookmarkrecht vereist.

  • pageUrl

    UrlFilter optioneel

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

RequestContentScript

Declaratieve gebeurtenisactie die een content script injecteert.

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

Eigenschappen

  • constructeur

    nietig

    De functie constructor ziet er zo uit: 

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

  • allFrames

    booleaans optioneel

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

  • css

    string[] optioneel

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

  • js

    string[] optioneel

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

  • matchAboutBlank

    booleaans optioneel

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

SetIcon

Declaratieve gebeurtenisactie die het vierkante n-dip-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 van 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 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 naar het vereiste formaat.

Eigenschappen

  • constructeur

    nietig

    De functie constructor ziet er zo uit: 

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

  • imageData

    ImageData | object optioneel

    Een ImageData-object of een woordenlijst {size -> ImageData} die een in te stellen icoon vertegenwoordigt. Als het icoon is gedefinieerd als een woordenlijst, wordt de gebruikte afbeelding gekozen op basis van de pixeldichtheid van het scherm. Als het aantal afbeeldingspixels dat in één schermruimteenheid 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 declaratie-gebeurtenisactie die de actie van de werkbalk van de extensie instelt op de status Aan als aan de bijbehorende voorwaarden wordt voldaan. Je kunt deze actie gebruiken zonder hostrechten. Als de extensie het recht activeTab heeft, krijgt de extensie toegang tot het actieve tabblad als de gebruiker op de pagina-actie klikt.

Op pagina's waar niet aan de voorwaarden wordt voldaan, is de werkbalkactie van de extensie grijsschaal. Als u 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 de status Aan als 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, krijgt de extensie toegang tot het actieve tabblad als de gebruiker op de pagina-actie klikt.

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

Eigenschappen

Evenementen

onPageChanged

Biedt de Declarative Event API met addRules, removeRules en getRules.

Voorwaarden

PageStateMatcher

Acties

RequestContentScript

SetIcon

ShowPageAction

ShowAction