chrome.declarativeContent

Beschreibung

Berechtigungen

Konzepte und Verwendung

Mit der Declarative Content API können Sie die Aktion Ihrer Erweiterung abhängig von der URL einer Webseite oder davon aktivieren, ob ein CSS-Sellektor mit einem Element auf der Seite übereinstimmt, ohne Hostberechtigungen hinzufügen oder ein Inhaltsskript einschleusen 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().

Die PageStateMatcher wird nur dann auf Webseiten angewendet, wenn alle aufgeführten Kriterien erfüllt sind. Es kann mit einer Seiten-URL, einem CSS-Komposit-Sellektor oder dem Zustand der Seitenmarkierung übereinstimmen. Mit der folgenden Regel wird die Aktion der Erweiterung auf Google-Seiten aktiviert, 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. Jede Bedingung reicht aus, 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() ]
};

Beim Ereignis onPageChanged wird geprüft, ob für eine Regel mindestens eine Bedingung erfüllt ist. Falls ja, werden die Aktionen ausgeführt. Regeln bleiben über Browsersitzungen hinweg erhalten. Daher sollten Sie während der Installation der Erweiterung zuerst removeRules verwenden, um zuvor installierte Regeln zu löschen, und dann addRules, um neue zu registrieren.

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

Wenn Sie die Berechtigung activeTab verwenden, werden in Ihrer Erweiterung keine Berechtigungswarnungen angezeigt. Wenn der Nutzer auf die Erweiterungsaktion klickt, wird sie nur auf relevanten Seiten ausgeführt.

Übereinstimmung der Seiten-URL

Die PageStateMatcher.pageurl stimmt überein, wenn die URL-Kriterien erfüllt sind. Die gängigsten Kriterien sind eine Koncatenate aus „host“, „path“ oder „url“, gefolgt von „enthält“, „gleich“, „präfix“ oder „suffix“. Die folgende Tabelle enthält einige Beispiele:

Kriterien	Übereinstimmungen
{ hostSuffix: 'google.com' }	Alle Google-URLs
{ pathPrefix: '/docs/extensions' }	URLs zu Erweiterungsdokumenten
{ urlContains: 'developer.chrome.com' }	URLs zu allen Chrome-Entwicklerdokumenten

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. Das bedeutet, dass Sie keine Kombinatoren wie Leerzeichen oder „>“ in Ihre Selektoren aufnehmen können. So kann Chrome die Auswahlmöglichkeiten effizienter abgleichen.

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 ist oder eines seiner übergeordneten Elemente display:none ist, wird die Bedingung nicht erfüllt. Elemente, die mit visibility:hidden formatiert, außerhalb des Bildschirms positioniert oder durch andere Elemente verdeckt sind, können trotzdem dazu führen, dass die Bedingung erfüllt wird.

Übereinstimmung des Status „Als Lesezeichen gespeichert“

Mit der Bedingung PageStateMatcher.isBookmarked kann der Status der aktuellen URL im Profil des Nutzers abgeglichen werden. Damit diese Bedingung verwendet werden kann, muss die Berechtigung „bookmarks“ im manifest der Erweiterung deklariert werden.