chrome.declarativeContent

Beschreibung

Berechtigungen

Konzepte und Nutzung

Mit der Declarative Content API können Sie die Aktion Ihrer Erweiterung abhängig von der URL einer Webseite aktivieren oder wenn ein CSS-Selektor mit einem Element auf der Seite übereinstimmt, ohne Hostberechtigungen hinzufügen oder ein Inhaltsskript einfügen zu müssen.

Verwenden Sie die Berechtigung activeTab, um mit einer Seite zu interagieren, nachdem der Nutzer auf die Aktion der Erweiterung geklickt hat.

Regeln

Regeln bestehen aus Bedingungen und Aktionen. Wenn eine der Bedingungen erfüllt ist, werden alle Aktionen ausgeführt. Die Aktionen sind setIcon() und showAction().

Das PageStateMatcher-Objekt stimmt nur dann mit Webseiten überein, wenn alle aufgeführten Kriterien erfüllt sind. Sie kann einer Seiten-URL, einem zusammengesetzten CSS-Selektor oder dem Lesezeichenstatus einer Seite entsprechen. Die folgende Regel aktiviert die Aktion der Erweiterung auf Google-Seiten, wenn ein Passwortfeld vorhanden ist:

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

Wenn Sie die Aktion der Erweiterung auch für Google-Websites mit einem Video aktivieren möchten, können Sie eine zweite Bedingung hinzufügen, da jede Bedingung ausreicht, um alle angegebenen Aktionen auszulösen:

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

Das Ereignis onPageChanged prüft, ob eine Regel mindestens eine erfüllte Bedingung hat, und führt die Aktionen aus. Die Regeln bleiben über mehrere Browsersitzungen hinweg bestehen. Daher sollten Sie während der Installation von Erweiterungen zuerst removeRules verwenden, um zuvor installierte Regeln zu löschen, und dann addRules verwenden, um neue Regeln zu registrieren.

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

Mit der Berechtigung activeTab zeigt Ihre Erweiterung keine Berechtigungswarnungen an. Wenn der Nutzer auf die Erweiterungsaktion klickt, wird sie nur auf relevanten Seiten ausgeführt.

Übereinstimmung der Seiten-URL

Wenn die URL-Kriterien erfüllt sind, wird als Ergebnis PageStateMatcher.pageurl zurückgegeben. Die häufigsten Kriterien sind eine Verkettung von Host, Pfad oder URL gefolgt von „Enthält“, „Ist gleich“, „Präfix“ oder „Suffix“. Die folgende Tabelle enthält einige Beispiele:

Kriterien	Übereinstimmungen
{ hostSuffix: 'google.com' }	Alle Google-URLs
{ pathPrefix: '/docs/extensions' }	Erweiterungsdokumentations-URLs
{ urlContains: 'developer.chrome.com' }	Alle URLs der Chrome-Entwicklerdokumentation

Bei allen Kriterien wird zwischen Groß- und Kleinschreibung unterschieden. Eine vollständige Liste der Kriterien finden Sie unter UrlFilter.

CSS-Abgleich

PageStateMatcher.css-Bedingungen müssen zusammengesetzte Selektoren sein, d. h., Sie können keine Kombinatoren wie Leerzeichen oder „>“ in Ihre Selektoren aufnehmen. So kann Chrome die Auswahl noch effizienter finden.

Zusammengesetzte Selektoren (OK)	Komplexe Selektoren (nicht zulässig)
a	div p
iframe.special[src^='http']	p>span.highlight
ns|*	p + ol
#abcd:checked	p::first-line

CSS-Bedingungen stimmen nur mit angezeigten Elementen überein: Wenn ein Element, das mit Ihrem Selektor übereinstimmt, display:none oder eines der übergeordneten Elemente display:none ist, führt dies nicht dazu, dass die Bedingung übereinstimmt. Durch Elemente mit visibility:hidden-Formatierung, außerhalb des sichtbaren oder von anderen Elementen ausgeblendeten Elementen kann die Bedingung trotzdem erfüllt werden.

Abgleich mit Lesezeichenstatus

Die Bedingung PageStateMatcher.isBookmarked ermöglicht den Abgleich des Lesezeichenstatus der aktuellen URL im Profil des Nutzers. Damit diese Bedingung genutzt werden kann, muss die Berechtigung „Lesezeichen“ im Manifest der Erweiterung deklariert werden.