chrome.declarativeContent

refresh date: 2026-09-25 robots: noindex

Beschreibung

Mit der chrome.declarativeContent API können Sie je nach Inhalt einer Seite Aktionen ausführen, ohne dass Sie die Berechtigung zum Lesen des Seiteninhalts benötigen.

Berechtigungen

declarativeContent

.

Nutzung

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-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.

Die PageStateMatcher stimmt nur dann mit Webseiten überein, wenn alle aufgeführten Kriterien erfüllt sind. Sie kann mit einer Seiten-URL, einem zusammengesetzten CSS-Selektor oder dem Lesezeichenstatus einer Seite ü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, 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() ]
};

Mit dem Ereignis onPageChanged wird geprüft, ob für eine Regel mindestens eine Bedingung erfüllt ist, und die Aktionen werden ausgeführt. Regeln bleiben über Browsersitzungen hinweg bestehen. Daher sollten Sie bei 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]);
  });
});

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

Seiten-URL-Abgleich

Die PageStateMatcher.pageurl wird ausgelöst, wenn die URL-Kriterien erfüllt sind. Die gängigsten Kriterien sind eine Verkettung von Host, Pfad oder URL, gefolgt von „Enthält“, „Ist gleich“, „Präfix“ oder „Suffix“. In der folgenden Tabelle finden Sie einige Beispiele:

Kriterien Übereinstimmungen
{ hostSuffix: 'google.com' } Alle Google-URLs
{ pathPrefix: '/docs/extensions' } URLs der Erweiterungsdokumentation
{ 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. Das bedeutet, dass Sie keine Kombinatoren wie Leerzeichen oder „>“ in Ihre Selektoren aufnehmen können. So kann Chrome die Selektoren effizienter abgleichen.

Zusammengesetzte Selektoren (OK) Komplexe Selektoren (nicht OK)
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, führt dies nicht dazu, dass die Bedingung erfüllt wird. Elemente, die mit visibility:hidden formatiert, außerhalb des Bildschirms positioniert oder von anderen Elementen verdeckt sind, können trotzdem dazu führen, dass die Bedingung erfüllt ist.

Abgleich des Lesezeichenstatus

Mit der Bedingung PageStateMatcher.isBookmarked kann der Lesezeichenstatus 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.

Typen

ImageDataType

Weitere Informationen finden Sie unter https://developer.mozilla.org/en-US/docs/Web/API/ImageData.

Typ

ImageData

PageStateMatcher

Entspricht dem Status einer Webseite basierend auf verschiedenen Kriterien.

Attribute

  • Konstruktor

    void

    Die Funktion constructor sieht so aus: 

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

  • css

    string[] optional

    Übereinstimmung, wenn alle CSS-Selektoren im Array mit angezeigten Elementen in einem Frame mit demselben Ursprung wie der Hauptframe der Seite übereinstimmen. Alle Selektoren in diesem Array müssen zusammengesetzte Selektoren sein, um den Abgleich zu beschleunigen. Hinweis: Wenn Sie Hunderte von CSS-Selektoren oder CSS-Selektoren auflisten, die hunderte Male pro Seite übereinstimmen, kann dies die Website verlangsamen.

  • isBookmarked

    Boolesch optional

    Chrome 45 oder höher

    Trifft zu, wenn der Lesezeichenstatus der Seite mit dem angegebenen Wert übereinstimmt. Erfordert die Berechtigung „bookmarks“.

  • pageUrl

    UrlFilter optional

    Trifft zu, wenn die Bedingungen von UrlFilter für die Top-Level-URL der Seite erfüllt sind.

RequestContentScript

Deklarative Ereignisaktion, die ein Inhaltsskript einfügt.

WARNUNG: Diese Aktion ist noch experimentell und wird in stabilen Chrome-Builds nicht unterstützt.

Attribute

  • Konstruktor

    void

    Die Funktion constructor sieht so aus: 

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

  • allFrames

    Boolesch optional

    Gibt an, ob das Inhaltsskript in allen Frames der übereinstimmenden Seite oder nur im obersten Frame ausgeführt wird. Standardwert ist false.

  • css

    string[] optional

    Namen von CSS-Dateien, die als Teil des Inhaltsskripts eingefügt werden sollen.

  • js

    string[] optional

    Namen von JavaScript-Dateien, die als Teil des Content-Scripts eingefügt werden sollen.

  • matchAboutBlank

    Boolesch optional

    Gibt an, ob das Inhaltsskript auf about:blank und about:srcdoc eingefügt werden soll. Der Standardwert ist false.

SetIcon

Deklarative Ereignisaktion, die das quadratische n-dip-Symbol für die Seitenaktion oder Browseraktion der Erweiterung festlegt, wenn die entsprechenden Bedingungen erfüllt sind. Diese Aktion kann ohne Hostberechtigungen verwendet werden, die Erweiterung muss jedoch eine Seiten- oder Browseraktion haben.

Es muss genau eines von imageData und path angegeben werden. Beide sind Wörterbücher, die eine Anzahl von Pixeln einer Bilddarstellung zuordnen. Die Bilddarstellung in imageData ist ein ImageData-Objekt, z. B. aus einem canvas-Element, während die Bilddarstellung in path der Pfad zu einer Bilddatei relativ zum Manifest der Erweiterung ist. Wenn scale Bildschirmpixel in ein geräteunabhängiges Pixel passen, wird das Symbol scale * n verwendet. Wenn diese Skalierung fehlt, wird ein anderes Bild auf die erforderliche Größe angepasst.

Attribute

  • Konstruktor

    void

    Die Funktion constructor sieht so aus: 

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

  • imageData

    ImageData | Objekt optional

    Entweder ein ImageData-Objekt oder ein Wörterbuch {size -> ImageData}, das ein festzulegendes Symbol darstellt. Wenn das Symbol als Wörterbuch angegeben ist, wird das verwendete Bild je nach Pixeldichte des Bildschirms ausgewählt. Wenn die Anzahl der Bildpixel, die in eine Bildschirmplatzeinheit passen, scale entspricht, wird ein Bild mit der Größe scale * n ausgewählt, wobei n die Größe des Symbols in der Benutzeroberfläche ist. Es muss mindestens ein Bild angegeben werden. details.imageData = foo entspricht details.imageData = {'16': foo}.

ShowAction

Chrome 97 oder höher

Eine deklarative Ereignisaktion, die die Aktion der Symbolleiste der Erweiterung auf einen aktivierten Status setzt, wenn die entsprechenden Bedingungen erfüllt sind. Diese Aktion kann ohne Hostberechtigungen verwendet werden. Wenn die Erweiterung die Berechtigung activeTab hat, wird durch Klicken auf die Seitenaktion Zugriff auf den aktiven Tab gewährt.

Auf Seiten, auf denen die Bedingungen nicht erfüllt sind, wird die Symbolleistenaktion der Erweiterung ausgegraut. Wenn Sie darauf klicken, wird das Kontextmenü geöffnet, anstatt die Aktion auszulösen.

Attribute

ShowPageAction

Seit Chrome 97 veraltet

Bitte verwende declarativeContent.ShowAction.

Eine deklarative Ereignisaktion, die die Seitenaktion der Erweiterung aktiviert, wenn die entsprechenden Bedingungen erfüllt sind. Diese Aktion kann ohne Hostberechtigungen verwendet werden, die Erweiterung muss jedoch eine Seitenaktion haben. Wenn die Erweiterung die Berechtigung activeTab hat, wird durch Klicken auf die Seitenaktion Zugriff auf den aktiven Tab gewährt.

Auf Seiten, auf denen die Bedingungen nicht erfüllt sind, wird die Symbolleistenaktion der Erweiterung ausgegraut. Wenn Sie darauf klicken, wird das Kontextmenü geöffnet, anstatt die Aktion auszulösen.

Attribute

Ereignisse

onPageChanged

Stellt die Declarative Event API bereit, die aus addRules, removeRules und getRules besteht.

Bedingungen

PageStateMatcher

Aktionen

RequestContentScript

SetIcon

ShowPageAction

ShowAction