chrome.declarativeContent

Beschrijving

Gebruik de chrome.declarativeContent API om acties te ondernemen afhankelijk van de inhoud van een pagina, zonder dat u toestemming nodig heeft om de inhoud van de pagina te lezen.

Machtigingen

declarativeContent

Concepten en gebruik

Met de Declarative Content API kunt u de actie van uw extensie inschakelen, afhankelijk van de URL van een webpagina, of als een CSS-selector overeenkomt met een element op de pagina, zonder dat u hostrechten hoeft toe te voegen of een inhoudsscript hoeft te injecteren.

Gebruik de activeTab- machtiging om met een pagina te communiceren nadat de gebruiker op de actie van de extensie heeft geklikt.

Regels

Regels bestaan ​​uit voorwaarden en acties. Als aan één van de voorwaarden is voldaan, worden alle acties uitgevoerd. De acties zijn setIcon() en showAction() .

De PageStateMatcher matcht webpagina's als en alleen als aan alle vermelde criteria wordt voldaan. Het kan overeenkomen met een pagina-URL , een samengestelde CSS-selector of de bladwijzerstatus van een pagina. De volgende regel schakelt de actie van de extensie op Google-pagina's in 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() ]
};

Om de actie van de extensie ook in te schakelen voor Google-sites met een video, kunt u een tweede voorwaarde toevoegen, aangezien elke voorwaarde voldoende is om alle opgegeven 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 onPageChanged gebeurtenis test of een regel aan ten minste één voorwaarde voldoet en voert de acties uit. Regels blijven bestaan ​​tijdens browsersessies; daarom moet u tijdens de installatie van de extensie eerst removeRules gebruiken om eerder geïnstalleerde regels te wissen en vervolgens 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 de activeTab- machtiging geeft uw extensie geen toestemmingswaarschuwingen weer en wanneer de gebruiker op de extensieactie klikt, wordt deze alleen op relevante pagina's uitgevoerd.

Overeenkomstige pagina-URL

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

Criteria Wedstrijden
{ hostSuffix: 'google.com' } Alle Google-URL's
{ pathPrefix: '/docs/extensions' } URL's van extensiedocumenten
{ urlContains: 'developer.chrome.com' } Alle Chrome-ontwikkelaars documenteren URL's

Alle criteria zijn hoofdlettergevoelig. Zie UrlFilter voor een volledige lijst met criteria.

CSS-matching

PageStateMatcher.css voorwaarden moeten samengestelde selectors zijn, wat betekent dat u geen combinators zoals witruimte of " > " in uw selectors kunt opnemen. Hierdoor kan Chrome de selectors efficiënter matchen.

Samengestelde selectors (OK) Complexe selectors (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 selector display:none of een van de bovenliggende elementen display:none is, zorgt dit er niet voor dat de voorwaarde overeenkomt. Elementen die met visibility:hidden zijn opgemaakt, buiten het scherm zijn geplaatst of door andere elementen zijn verborgen, kunnen er nog steeds voor zorgen dat uw voorwaarde overeenkomt.

Staatsmatching met bladwijzer

Met de voorwaarde PageStateMatcher.isBookmarked kan de bladwijzerstatus van de huidige URL in het gebruikersprofiel worden vergeleken. Om van deze voorwaarde gebruik te kunnen maken, moet de toestemming "bladwijzers" worden aangegeven in het extensiemanifest .

Soorten

Type

Beeldgegevens

PageStateMatcher

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

Eigenschappen

  • bouwer

    leegte

    De constructor ziet er als volgt uit: 

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

  • css

    tekenreeks[] optioneel

    Komt overeen als alle CSS-kiezers in de array overeenkomen met weergegeven elementen in een frame met dezelfde oorsprong als het hoofdframe van de pagina. Alle selectors in deze array moeten samengestelde selectors zijn om het matchen te versnellen. Opmerking: het vermelden van honderden CSS-selectors of het vermelden van CSS-selectors die honderden keren per pagina overeenkomen, kan websites vertragen.

  • is een bladwijzer

    Booleaans optioneel

    Chroom 45+

    Komt overeen als de bladwijzerstatus van de pagina gelijk is aan de opgegeven waarde. Vereist toestemming voor bladwijzers .

  • paginaUrl

    UrlFilter optioneel

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

RequestContentScript

Declaratieve gebeurtenisactie die een inhoudsscript injecteert.

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

Eigenschappen

  • bouwer

    leegte

    De constructor ziet er als volgt uit: 

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

  • alleFrames

    Booleaans optioneel

    Of het inhoudsscript in alle frames van de overeenkomende pagina wordt uitgevoerd, of alleen in het bovenste frame. Standaard is false .

  • css

    tekenreeks[] optioneel

    Namen van CSS-bestanden die moeten worden geïnjecteerd als onderdeel van het inhoudsscript.

  • js

    tekenreeks[] optioneel

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

  • matchOverBlank

    Booleaans optioneel

    Of het inhoudsscript moet worden ingevoegd in about:blank en about:srcdoc . Standaard is false .

SetIcon

Declaratieve gebeurtenisactie die het vierkante n-dip-pictogram instelt voor de pagina- of browseractie van de extensie terwijl aan de overeenkomstige 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 opgegeven. Beide zijn woordenboeken die een aantal pixels toewijzen aan een afbeeldingsrepresentatie. De beeldweergave in imageData is een ImageData- object; bijvoorbeeld van een canvas , terwijl de afbeeldingsrepresentatie in path het pad is naar een afbeeldingsbestand ten opzichte van het manifest van de extensie. Als scale in een apparaatonafhankelijke pixel passen, wordt het scale * n pictogram gebruikt. Als die schaal ontbreekt, wordt een andere afbeelding verkleind naar de gewenste grootte.

Eigenschappen

  • bouwer

    leegte

    De constructor ziet er als volgt uit: 

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

  • afbeeldingGegevens

    Beeldgegevens | object optioneel

    Een ImageData object of een woordenboek {size -> ImageData} die een in te stellen pictogram vertegenwoordigt. Als het pictogram als woordenboek is opgegeven, wordt de gebruikte afbeelding gekozen op basis van de pixeldichtheid van het scherm. Als het aantal beeldpixels dat in één schermruimte-eenheid past gelijk is aan scale , dan wordt een afbeelding met grootteschaal scale * n geselecteerd, waarbij n de grootte is van het pictogram in de gebruikersinterface. Er moet ten minste één afbeelding worden opgegeven. Houd er rekening mee dat details.imageData = foo gelijk is aan details.imageData = {'16': foo} .

ShowAction

Chroom 97+

Een declaratieve gebeurtenisactie die de werkbalkactie van de extensie in de ingeschakelde status zet terwijl aan de overeenkomstige voorwaarden wordt voldaan. Deze actie kan worden gebruikt zonder hostmachtigingen . Als de extensie de activeTab- machtiging heeft, geeft het klikken op de paginaactie toegang tot het actieve tabblad.

Op pagina's waar niet aan de voorwaarden wordt voldaan, zal de werkbalkactie van de extensie grijswaarden hebben, en als u erop klikt, wordt het contextmenu geopend in plaats van dat de actie wordt geactiveerd.

Eigenschappen

ShowPageAction

Verouderd sinds Chrome 97

Gebruik declarativeContent.ShowAction .

Een declaratieve gebeurtenisactie die de paginaactie van de extensie inschakelt terwijl aan de bijbehorende voorwaarden wordt voldaan. Deze actie kan worden gebruikt zonder hostrechten , maar de extensie moet een paginaactie hebben. Als de extensie de activeTab- machtiging heeft, geeft het klikken op de paginaactie toegang tot het actieve tabblad.

Op pagina's waar niet aan de voorwaarden wordt voldaan, zal de werkbalkactie van de extensie grijswaarden hebben, en als u erop klikt, wordt het contextmenu geopend in plaats van dat de actie wordt geactiveerd.

Eigenschappen

Evenementen

onPageChanged

Biedt de Declaratieve gebeurtenis-API die bestaat uit addRules , removeRules en getRules .

Voorwaarden

PageStateMatcher

Acties

RequestContentScript

SetIcon

Toon PaginaActie

ToonActie